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.
For PHP platforms and developers, we've developed a generic PHP class.
For Java developers, the implementation should be straightforward. We intend to provide example code for a client implementation though (available soon).
We also provide a small Python script called murl to manually query all the REST API endpoints (slightly inspired by cURL).
The REST API may see small additions over time. Follow us on Twitter to stay updated.
We highly welcome and appreciate any kind of feedback you have. Please don’t hesitate to contact us!
Mollom's previous XML-RPC API is deprecated. The XML-RPC API documentation is still available though.
Table of Contents
- API endpoints
- General request format
- General response format
- Site API
- Blacklist API
- Whitelist API
- Content API
- CAPTCHA API
- Feedback API
API endpoints
- There is a production system and a testing system:
http://rest.mollom.com/v1is the REST API endpoint for production usage.http://dev.mollom.com/v1is 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.comendpoint 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.
- Do not send OAuth authentication parameters to create a testing site.
- You can create unlimited testing sites as needed.
- Deleting a site after running tests is encouraged but not required.
- Differences to production API:
- Content API only reacts to literal strings
"spam","ham", and"unsure"in thepostTitleandpostBodyparameters. If none of the literal strings is contained, and also no blacklist or whitelist values matched, the finalspamClassificationwill be"unsure". - CAPTCHA API only reacts to literal strings
"correct"and"incorrect"in thesolutionparameter for image CAPTCHAs and the literal string"demo"for audio CAPTCHAs. If none of the literal strings is sent,solvedwill be0(false).
- Content API only reacts to literal strings
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
AuthorizationHTTP 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 formchecks=spam&checks=quality.Note for PHP developers: PHP's native syntax for multiple request parameters (i.e.,
checks[]=spam) is not supported. The generic Mollom PHP class provides necessary helper functions to build and parse multiple parameters. - Use the HTTP
Acceptheader to specify the desired response format. - HTTP
POSTrequests must be accompanied with aContent-TypeHTTP 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
Acceptrequest header to ask for a different format, if available. 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: Success401: 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
Syntax: GET http://rest.mollom.com/v1/{resource}
Request parameters
offset: 0-n (optional, default = 0)
The number of items to not include in the returned list, counting from 0.count: 1-n (optional, default = all)
The number of items to return.
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>
list: Generic wrapper for listed resources/entities. Can be empty (but always exists) iflistTotal = 0.listCount: The amount of items contained in the response (paging). May be less than requested.listOffset: The amount of items that have been skipped but exist before the items returned (paging).listTotal: The 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). contentIdandcaptchaIdeach have a maximum length of 36 characters.
Site API
Create a site
Syntax: POST http://rest.mollom.com/v1/site
Request parameters
url:
The URL of the new site.email:
The primary contact e-mail of the site.languages: (optional)
ISO codes of languages, content is expected to submitted in on the site.platformName: (optional)
The name of the platform running the site (e.g.,"Drupal").platformVersion: (optional)
The version of the platform running the site (e.g.,"6.20").clientName: (optional)
The name of the Mollom client plugin used (e.g.,"Mollom").clientVersion: (optional)
The version of the Mollom client plugin used (e.g.,"1.15").
Response format
<response>
<code>200</code>
<message>Error message</message>
<site>
<id>siteId</id>
<publicKey>publicKey</publicKey>
<privateKey>privateKey</privateKey>
<url>example.com</url>
<email>mail@example.com</email>
<languages>
<language>en</language>
</languages>
<subscriptionType></subscriptionType>
<platformName>Drupal</platformName>
<platformVersion>7.2</platformVersion>
<clientName>Mollom</clientName>
<clientVersion>7.x-1.0</clientVersion>
</site>
</response>
Update a site (also: Verify keys and send client information)
Syntax: POST http://rest.mollom.com/v1/site/{publicKey}
Path parameters
publicKey: The public API key of the site.
Request parameters
platformName: (optional, default = keep existing)
The name of the platform running the site (e.g.,"Drupal").platformVersion: (optional, default = keep existing)
The version of the platform running the site (e.g.,"6.20").clientName: (optional, default = keep existing)
The name of the Mollom client plugin used (e.g.,"Mollom").clientVersion: (optional, default = keep existing)
The version of the Mollom client plugin used (e.g.,"1.15").url: (optional, default = keep existing)
The URL of the new site. Can only be updated by Mollom resellers.email: (optional, default = keep existing)
The primary contact e-mail of the site. Can only be updated by Mollom resellers.languages: (optional, default = keep existing)
ISO codes of languages, content is expected to submitted in on the site. Can only be updated by Mollom resellers.
Response format
<response>
<code>200</code>
<message>Error message</message>
<site>
<id>siteId</id>
<publicKey>publicKey</publicKey>
<privateKey>privateKey</privateKey>
<url>example.com</url>
<email>mail@example.com</email>
<languages>
<language>en</language>
</languages>
<subscriptionType></subscriptionType>
<platformName>Drupal</platformName>
<platformVersion>7.2</platformVersion>
<clientName>Mollom</clientName>
<clientVersion>7.x-1.0</clientVersion>
</site>
</response>
List sites
Syntax: GET http://rest.mollom.com/v1/site
Returns a list of all sites that can be accessed with the given authentication.
Request parameters
- List parameters (optional)
Response format
<response>
<code>200</code>
<message>Error message</message>
<list>
<site>
<id>siteId</id>
<publicKey>publicKey</publicKey>
...
</site>
</list>
<listCount>20</listCount>
<listOffset>0</listOffset>
<listTotal>123</listTotal>
</response>
Read a site
Syntax: GET http://rest.mollom.com/v1/site/{publicKey}
Path parameters
publicKey: The public API key of the site.
Response format
<response>
<code>200</code>
<message>Error message</message>
<site>
<id>siteId</id>
<publicKey>publicKey</publicKey>
<privateKey>privateKey</privateKey>
<url>example.com</url>
<email>mail@example.com</email>
<languages>
<language>en</language>
</languages>
<subscriptionType></subscriptionType>
<platformName>Drupal</platformName>
<platformVersion>7.2</platformVersion>
<clientName>Mollom</clientName>
<clientVersion>7.x-1.0</clientVersion>
</site>
</response>
Delete a site
Syntax: POST http://rest.mollom.com/v1/site/{publicKey}/delete
Path parameters
publicKey: The public API key of the site.
Response format
<response> <code>200</code> <message>Error message</message> </response>
Error handling
- HTTP
200("OK") + code200- The site was deleted.
- HTTP
404("Unknown site") + empty response- The site does not exist.
Blacklist API
Create a Blacklist entry
Syntax: POST http://rest.mollom.com/v1/blacklist/{publicKey}
Path parameters
publicKey: The public API key of a Mollom site.
Request parameters
value:
The string/value to blacklist.reason:{"spam"|"profanity"|"quality"|"unwanted"}(optional, default = "unwanted")
A string denoting the reason for why the value is blacklisted.context:{"allFields"|"authorName"|"authorMail"|"authorIp"|"authorId"|"links"|"postTitle"}(optional, default = "allFields")
A string denoting where the entry's value may match.match:{"exact"|"contains"}(optional, default = "contains")
A string denoting how precise the entry's value may match.status:{0|1}(optional, default = 1)
An integer denoting whether the entry is enabled or not.note: (optional)
A custom string explaining the entry. Useful in a multi-moderator scenario.
Response format
<response>
<code>200</code>
<message>Error message</message>
<entry>
<id>blacklistEntryId</id>
<created>1305657479</created>
<status>1</status>
<lastMatch></lastMatch>
<matchCount>0</matchCount>
<value>viagra</value>
<reason>spam</reason>
<context>allFields</context>
<match>contains</match>
<note></note>
</entry>
</response>
Update a Blacklist entry
Syntax: POST http://rest.mollom.com/v1/blacklist/{publicKey}/{blacklistEntryId}
Path parameters
publicKey: The public API key of a Mollom site.blacklistEntryId: The ID of an existing blacklist entry.
Request parameters
value: (optional, default = keep existing)
The string/value to blacklist.reason:{"spam"|"profanity"|"quality"|"unwanted"}(optional, default = keep existing)
A string denoting the reason for why the value is blacklisted.context:{"allFields"|"authorName"|"authorMail"|"authorIp"|"authorId"|"links"|"postTitle"}(optional, default = keep existing)
A string denoting where the entry's value may match.match:{"exact"|"contains"}(optional, default = keep existing)
A string denoting how precise the entry's value may match.status:{0|1}(optional, default = keep existing)
An integer denoting whether the entry is enabled or not.note: (optional, default = keep existing)
A custom string explaining the entry. Useful in a multi-moderator scenario.
Delete a Blacklist entry
Syntax: POST http://rest.mollom.com/v1/blacklist/{publicKey}/{blacklistEntryId}/delete
Path parameters
publicKey: The public API key of a Mollom site.blacklistEntryId: The ID of an existing blacklist entry.
Response format
<response> <code>200</code> <message>Error message</message> </response>
Error handling
- HTTP
200("OK") + code200- The entry was deleted.
- HTTP
404("Unknown blacklist entry") + empty response- The entry does not exist.
List Blacklist
Syntax: GET http://rest.mollom.com/v1/blacklist/{publicKey}
Path parameters
publicKey: The public API key of a Mollom site.
Request parameters
- List parameters (optional)
Response format
<response>
<code>200</code>
<message>Error message</message>
<list>
<entry>
<id>blacklistEntryId</id>
<created></created>
...
</entry>
</list>
<listCount>20</listCount>
<listOffset>0</listOffset>
<listTotal>123</listTotal>
</response>
Read a Blacklist entry
Syntax: GET http://rest.mollom.com/v1/blacklist/{publicKey}/{blacklistEntryId}
Path parameters
publicKey: The public API key of a Mollom site.blacklistEntryId: The ID of an existing blacklist entry.
Response format
<response>
<code>200</code>
<message>Error message</message>
<entry>
<id>1234</id>
<created>1305657479</created>
<status>1</status>
<lastMatch>1305657470</lastMatch>
<matchCount>123</matchCount>
<value>viagra</value>
<reason>spam</reason>
<context>allFields</context>
<match>contains</match>
<note></note>
</entry>
</response>
Whitelist API
Whitelist entries are checked first. On a positive whitelist match, no other checks are performed; i.e.:
- Content API's spam check returns ham.
- Content API's profanity check returns non-profane.
- Blacklist entries are not checked.
If no whitelist entry matches, all APIs work as usual.
Create a Whitelist entry
Syntax: POST http://rest.mollom.com/v1/whitelist/{publicKey}
Path parameters
publicKey: The public API key of a Mollom site.
Request parameters
value:
The string/value to whitelist.context:{"authorIp"|"authorId"|"authorName"|"authorMail"}
A string denoting where the entry's value may match.status:{0|1}(optional, default = 1)
An integer denoting whether the entry is enabled or not.note: (optional)
A custom string explaining the entry. Useful in a multi-moderator scenario.
Response format
<response>
<code>200</code>
<message>Error message</message>
<entry>
<id>whitelistId</id>
</entry>
</response>
Update a Whitelist entry
Syntax: POST http://rest.mollom.com/v1/whitelist/{publicKey}/{whitelistEntryId}
Path parameters
publicKey: The public API key of a Mollom site.whitelistEntryId: The ID of an existing whitelist entry.
Request parameters
value: (optional, default = keep existing)
The string/value to whitelist.context:{"authorIp"|"authorId"|"authorName"|"authorMail"}(optional, default = keep existing)
A string denoting where the entry's value may match.status:{0|1}(optional, default = keep existing)
An integer denoting whether the entry is enabled or not.note: (optional, default = keep existing)
A custom string explaining the entry. Useful in a multi-moderator scenario.
Delete a Whitelist entry
Syntax: POST http://rest.mollom.com/v1/whitelist/{publicKey}/{whitelistEntryId}/delete
Path parameters
publicKey: The public API key of a Mollom site.whitelistEntryId: The ID of an existing whitelist entry.
Response format
<response> <code>200</code> <message>Error message</message> </response>
Error handling
- HTTP
200("OK") + code200- The entry was deleted.
- HTTP
404("Unknown blacklist entry") + empty response- The entry does not exist.
List Whitelist
Syntax: GET http://rest.mollom.com/v1/whitelist/{publicKey}
Path parameters
publicKey: The public API key of a Mollom site.
Request parameters
- List parameters (optional)
Response format
<response>
<code>200</code>
<message>Error message</message>
<list>
<entry>
<id>whitelistEntryId</id>
<created></created>
...
</entry>
</list>
<listCount>20</listCount>
<listOffset>0</listOffset>
<listTotal>123</listTotal>
</response>
Read a Whitelist entry
Syntax: GET http://rest.mollom.com/v1/whitelist/{publicKey}/{whitelistEntryId}
Path parameters
publicKey: The public API key of a Mollom site.whitelistEntryId: The ID of an existing whitelist entry.
Response format
<response>
<code>200</code>
<message>Error message</message>
<entry>
<id>whitelistEntryId</id>
<created></created>
<status></status>
<lastMatch></lastMatch>
<matchCount></matchCount>
<value></value>
<context></context>
<note></note>
</entry>
</response>
Content API
Create (and check) content
Syntax: POST http://rest.mollom.com/v1/content
To re-check a post that was checked before, update the content instead of creating a new.
Request parameters
postTitle: (optional)
The title of the content.postBody: (optional)
The body of the content.authorName: (optional)
The name of the content author.authorUrl: (optional)
The homepage/website URL of the content author.authorMail: (optional)
The e-mail address of the content author.authorIp: (optional)
The IP address of the content author.authorId: (optional)
The local user ID on the client site of the content author.authorOpenid: (multiple, optional)
Open IDs of the content author, separated by whitespace.checks:{"spam"|"quality"|"profanity"|"language"}(multiple, optional, default = spam|none)
A string denoting the check to perform. If omitted, defaults to"spam"for new content (without{contentId}). No checks are performed by default for existing content (with{contentId}).unsure:{1|0}(optional, default = 1)
Integer denoting whether a "unsure" response should be allowed for the 'spam' check (which should lead to CAPTCHA) or not.strictness:{"strict"|"normal"|"relaxed"}(optional, default = normal)
A string denoting the strictness of Mollom checks to perform.rateLimit: (optional, default = 15)
Seconds that must have passed by for the same author to post again.honeypot: (optional)
The value of a client-side honeypot form element, if non-empty.stored: (optional, default = 0)
Whether the content has been stored on the client-side. Use0during form validation,1after successful form submission.url: (optional)
The absolute URL to the stored content.contextUrl: (optional)
An absolute URL to parent/context content of the stored content; e.g., the URL of the article or forum thread a comment is posted on (not the parent comment that was replied to).contextTitle: (optional)
The title of the parent/context content of the stored content; e.g., the title of the article or forum thread a comment is posted on (not the parent comment that was replied to).
Response format
<response>
<code>200</code>
<message>Error message</message>
<content>
<id>contentId</id>
<spamScore>0.0</spamScore>
<spamClassification>{ham|spam|unsure}</spamClassification>
<profanityScore>0.0</profanityScore>
<qualityScore>0.0</qualityScore>
<sentimentScore>0.0</sentimentScore>
<reason></reason>
<languages>
<language>
<languageCode>en</languageCode>
<languageScore>1.0</languageScore>
</language>
<language>
<languageCode>de</languageCode>
<languageScore>0.5</languageScore>
</language>
</languages>
<postTitle></postTitle>
<postBody></postBody>
<authorName></authorName>
<authorUrl></authorUrl>
<authorMail></authorMail>
<authorIp></authorIp>
<authorId></authorId>
<authorOpenid>
<id></id>
<id></id>
</authorOpenid>
</content>
</response>
Response parameters
contentId:
If contained in the request and it can be validated in the system, the same is returned. Otherwise, a new uniquecontentIdis returned.*scoreand*classification: (optional)
These elements are only returned when requested inchecks; e.g.,checks=spamreturnsspamScoreandspamClassificationchecks=profanityreturnsprofanityScore- etc.
*scorevalues are floating point values with a precision of 2, ranging between0.00and1.00.spamScore = 0.0means ham (0% spam).spamScore = 1.0means spam (100% spam).spamScore = 0.5means unsure (50% spam).profanityScore = 0.0means not profane (0% profane).profanityScore = 1.0means profane (100% profane).- etc.
Depending on a site's Mollom subscription plan, the returned scores can be real values between 0 and 1.
reason: (optional)
A single-word string denoting the reason for the content classification; e.g.:"rateLimit": Author was seen on Mollom-protected sites within the givenrateLimittime-frame.- ...
Update (and optionally re-check) content
Syntax: POST http://rest.mollom.com/v1/content/{contentId}
Path parameters
contentId: Existing content ID.
Request parameters
The content is only re-checked if the checks parameter is passed. Otherwise, the content properties are updated only.
See Create content.
Captcha API
Create a CAPTCHA resource
Syntax: POST http://rest.mollom.com/v1/captcha
Request parameters
type:{"image"|"audio"}
The type of CAPTCHA to create.ssl:{1|0}(optional, default = 0)
Whether to create a CAPTCHA URL using HTTPS. Only available for paid subscriptions.contentId: (optional)
The ID of a content resource to link the CAPTCHA to. Allows Mollom to learn when it was unsure.
Response format
<response>
<code>200</code>
<message>Error message</message>
<captcha>
<id>captchaId</id>
<url>http://my.captcha/location.png</url>
<solved>0</solved>
<reason></reason>
<authorName></authorName>
<authorUrl></authorUrl>
<authorMail></authorMail>
<authorIp></authorIp>
<authorId></authorId>
<authorOpenid></authorOpenid>
</captcha>
</response>
Retrieve a CAPTCHA resource
Syntax: GET {captchaUrl}
Unlike all other API calls, CAPTCHA resources are requested by the client-side browser of an end-user.
Path parameters
captchaUrl: The URL of a CAPTCHA resource, as returned by Mollom.
CAPTCHA resources have to be explicitly created prior to using them. The resource URL cannot be constructed manually.
Response format
@Produces media
Error handling
- HTTP
200("OK") + raw media content- The CAPTCHA resource exists and can be delivered.
- HTTP
404("Unknown CAPTCHA resource") + empty response- The CAPTCHA resource does not exist.
- HTTP
409("CAPTCHA was processed already") + empty response- The CAPTCHA resource exists, but was already processed/updated (solved or not), and can no longer be shown or solved.
- HTTP
410("Expired CAPTCHA") + empty response- The CAPTCHA resource previously existed, but has expired and can no longer be shown or solved.
Verify a captcha
Syntax: POST http://rest.mollom.com/v1/captcha/{captchaId}
Path parameters
captchaId: The ID of the CAPTCHA resource.
Request parameters
solution:
The answer provided by the author.authorName: (optional)
The name of the content author.authorUrl: (optional)
The homepage/website URL of the content author.authorMail: (optional)
The e-mail address of the content author.authorIp: (optional)
The IP address of the content author.authorId: (optional)
The local user ID of the content author on the client site.authorOpenid: (multiple, optional)
One or more Open IDs of the content author.rateLimit: (optional, default = 15)
Seconds that must have passed by for the same author to post again.honeypot: (optional)
Client-side honeypot value, if non-empty.
Response format
<response>
<code>200</code>
<message>Error message</message>
<captcha>
<id>captchaId</id>
<solved>1</solved>
<reason>rateLimit</reason>
<authorName></authorName>
<authorUrl></authorUrl>
<authorMail></authorMail>
<authorIp></authorIp>
<authorId></authorId>
<authorOpenid></authorOpenid>
</captcha>
</response>
solved:
Whether the providedsolutionwas correct (1) or not (0).reason: (optional)
A single-word string denoting the reason for why the CAPTCHAsolutionwas deemed to be incorrect:"rateLimit": Author was seen on Mollom-protected sites within the givenrateLimittime-frame."expired": The CAPTCHA resource expired.- ...
Error handling
- HTTP
200("OK") + code200+ (optional) reason- The CAPTCHA resource exists and was
solved(1) or not (0).
- The CAPTCHA resource exists and was
- HTTP
404("Not found") + empty response- The CAPTCHA resource does not exist.
- HTTP
410("Gone") + code410+ reasonexpired- The CAPTCHA resource previously existed, but has expired and can no longer be solved.
Feedback API
Send feedback
Syntax: POST http://rest.mollom.com/v1/feedback
Request parameters
contentId: (optional) Existing content ID.captchaId: (optional) Existing CAPTCHA ID.reason:{"approve"|"spam"|"profanity"|"quality"|"unwanted"|"delete"}
A string denoting the reason for why the content associated with either contentId or captchaId is being reported.
Either a contentId or a captchaId is required.
Response format
<response> <code>200</code> <message>Error message</message> </response>
Error handling
- HTTP
200("OK") + code200- The feedback was stored.
- HTTP
400("Missing resource ID") + empty response- Neither a
contentIdnor acaptchaIdwas specified.
- Neither a
- HTTP
400("Invalid reason") + empty response- A
reasonwas specified, but it's not one of the supported strings.
- A
- HTTP
404("Not found") + empty response- The supplied
contentIdand/orcaptchaIdcould not be found.
- The supplied
