Mollom REST API

Mollom REST API

Mollom provides a REST API that is based on widely adopted RESTful patterns and best practices. It allows for simple Mollom client implementations and enables them for new Mollom features and products.

Using the REST API

API endpoints

  • There is a production system and a testing system:
    • http://rest.mollom.com/v1 is the REST API endpoint for production usage.
    • http://dev.mollom.com/v1 is the REST API endpoint for testing client implementations.
  • The API version number is prefixed to all REST paths. Currently "v1".

Testing API for clients

  • Use the dev.mollom.com endpoint to test your REST API client implementation.
  • Before doing any API calls, you have to create a site for testing and use its keys for all subsequent requests.
  • Differences to production API:
    • Content API only reacts to the literal strings spam, ham, and unsure in the postTitle and postBody parameters. If none of the literal strings is contained, and also no blacklist or whitelist values matched, the final spamClassification will be unsure.
    • CAPTCHA API only reacts to the literal strings correct and incorrect in the solution parameter for image CAPTCHAs and the literal string demo for audio CAPTCHAs. If none of the literal strings are sent, solved will be 0 (false).

Request format

  • Every API call requires authentication to identify the site a request originates from.
    • Two-legged OAuth 1.0 protocol parameters are used for signing requests, using the public Mollom API key as client/consumer key, and the private Mollom API key as client/consumer secret.
    • Use the Authorization HTTP header to pass OAuth protocol parameters.
    • Ensure your implementation follows the RFC 5849 OAuth 1.0 Protocol specification.
    • The maximum allowed server time offset for the OAuth signature timestamp is 5 minutes.
  • Certain request parameters can be specified multiple times. These are marked with (multiple) in this document.
    Multiple parameter values are specified in the form checks=spam.
  • Use the HTTP Accept header to specify the desired response format.
  • HTTP POST requests must be accompanied with a Content-Type HTTP header when the request body contains parameters:

    Content-Type: application/x-www-form-urlencoded

Response format

  • All responses can be in XML or JSON. The default format is XML.
  • Use the HTTP Accept request header to ask for a different format, if available. For example:

    Accept: application/xml, application/json;q=0.8, */*;q=0.5

    See RFC 2616 HTTP Accept header for details.

Status code

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
</response>

  • code:
    An application-level status code, returned in addition to the (corresponding, if possible) HTTP status code.
    • 200: Success
    • 401: Unauthorized (Authentication failure)
    • 403: Forbidden (Authentication does not allow to access requested resource)
    • 404: Not found
  • message: (optional)
    An application-level status message clarifying the status code (in case of an error).

List responses

GET http://rest.mollom.com/v1/{resource}

Request parameters

Parameter Type Description Accepted values
offset Integer Optional - Number of items to not include in the returned list, counting from 0; default = 0 0 to n
count Integer Optional - Number of items to return; default = all 1 to n

Response format

<response>
  <code>200</ code>
  <message>Error message</message>
  <list>
    <{resource}>
      <id>resourceId</id>
      ...
    </{resource}>
  </list>
  <listCount>20</listCount>
  <listOffset>0</listOffset>
  <listTotal>123</listTotal>
</response>

Returned value Description
list Generic wrapper for listed resources/entities; can be empty (but always exists) if listTotal = 0
listCount Amount of items contained in the response (paging); may be less than requested
listOffset Amount of items that have been skipped but exist before the items returned (paging)
listTotal Total amount of available items (paging)

Resource IDs

  • All resource IDs returned by Mollom are Universally Unique Identifiers (UUIDs).
  • All resource IDs should be treated as strings.
  • In responses, a resource ID is contained in a element of name id.
  • In request parameters, an associated resource ID is specified with an explicit name; e.g., contentId={id} (unless contained in the URI).
  • contentId and captchaId each have a maximum length of 36 characters.

Additional Resources

For PHP platforms and developers, we've developed a generic PHP class and example custom implementation.

For Java developers, we've developed a Java client library. The library uses the Jersey REST client library to perform Mollom API requests.

We also provide a small Python script called murl to manually query all the REST API endpoints (slightly inspired by cURL).