9.1. mollom.getServerList

Note

The Mollom XML-RPC API interface has been deprecated, and is included here for archival purposes.

To develop clients and services that connect to Mollom, use the Mollom REST API.

mollom.getServerList
Required Name Type Description
required public_key string Site public key
required time string Site server time in this format: yyyy-MM-dd'T'HH:mm:ss-.SSSZ
required hash string HMAC-SHA1 digest
required nonce string One time nonce
optional ssl boolean Use SSL for all api calls
returns array of strings Array of servers that can be used

This remote procedure call obtains the list of valid Mollom servers, needed to initiate traffic with the Mollom servers. The order of the servers in the list is important. Always use the first server in the list, unless that server is unavailable. A server is unavailable on the return of a network error or an XML-RPC error other than 1000, 1100 or 1200 (see Section 6 and Figure 2).

It would be a waste of overhead to call mollom.getServerList before every Mollom API call or HTTP request. Clients should include code to cache the server list for an extended time using either a database- or file-cache. Clients can be designed to refresh the server list once every few days or weeks, but this is not necessary. Mollom will return the 1100 error code if it needs a client to update its cached server list.

Clients should also request a new server list if they don't have one or if all of the listed servers fail. A new server list can be retrieved from any Mollom server, but when no servers are currently assigned or when they have all failed, the mollom.getServerList call should be directed to either http://xmlrpc1.mollom.com, http://xmlrpc2.mollom.com or http://xmlrpc3.mollom.com. Figure 2 illustrates in more detail how this mechanism should be implemented.

In other words, before every remote procedure call, the client should execute something along the lines of the following code, taken from the Drupal 6 Mollom module available at http://mollom.com/download:


// Retrieve the list of Mollom servers from the database:
$servers = variable_get('mollom_servers', NULL);
if ($servers == NULL) {
  // Initialize server list:
  $servers = _mollom_retrieve_server_list();
  
  // Store the list of servers in the database:
  variable_set(`mollom_servers', $servers);
}

If the server list is not yet initialized, the client needs to retrieve a server list from mollom.com as shown in the subroutine in Figure 2:


function _mollom_retrieve_server_list() {
  // Start from a hard coded list of servers:
  $servers = array('http://xmlrpc1.mollom.com',
    'http://xmlrpc2.mollom.com',
    'http://xmlrpc3.mollom.com');
  
  // Retrieve the actual server list from mollom.com:
  foreach ($servers as $server) {
    $result = xmlrpc($server .'/'. MOLLOM_API_VERSION, `mollom.getServerList',
    _mollom_authentication());
    if (!xmlrpc_errno()) {
      return $result;
    }
  }
  
  return array();
}

Once the client has a valid list of Mollom servers, it can execute the actual remote procedure call as follows:


if (is_array($servers)) {
  // Send the request to the first server, if that fails, try the
  // other servers in the list:
  foreach ($servers as $server) {
    $result = xmlrpc($server . '/1.0', $method, $data + _mollom_authentication());
    if ($errno = xmlrpc_errno()) {
      if ($errno == MOLLOM_REFRESH) {
        // Retrieve new server list from current server:
        $servers = _mollom_retrieve_server_list();
  
        // Store the updated list of servers in the database:
        variable_set('mollom_servers', $servers);
      }
      else if ($errno == MOLLOM_ERROR) {
        return $result;
      }
      else if ($errno == MOLLOM_REDIRECT) {
        // Do nothing, we select the next server automatically.
      }
    }
    else {
      return $result;
    }
  }
}
  
// If everything fails, we reset the server list to force loading of a new list:
variable_set('mollom_servers', array());

Mollom Premium users can set the ssl parameter to true. This will supply a list of servers that are capable of accepting secured connections. All api calls to those servers can be routed over secure connections. The ssl parameter will be ignored for Mollom Free and Mollom Plus users.