Using the Mollom REST API

Mollom REST API

• Using
• List

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 (currently v1) is prefixed to all REST parameters.

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 website for testing and use its keys for all subsequent requests.
  • Do not send OAuth authentication parameters to create a testing website.
  • You can create unlimited testing websites as needed.
  • Deleting a website after running tests is encouraged but not required.
• 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 website 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

• 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

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; for example, 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 have developed a generic PHP class and example custom implementation.

For Java developers, we have 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).