This is version 0.2.1 of the spec.

The Profanity Filter Communication API is designed to allow different installations of Profanity Filter to subscribe to and share lists of words with each other.

Each request is a GET request to the root of a forum. The required parameters are:

Parameter Description
profanity_filter_subscribe The type of request.
profanity_filter_version The latest version of Profanity Filter in which the API changed. If these are different on the subscriber and the host, an error will be returned.
profanity_filter_url A URL to the forum where Profanity Filter is being used. This is the URL of the forum that is sending the request.
profanity_filter_key An SHA1 hash of SECRET + colon + TIMESTAMP. This is omitted in subscribe requests because no SECRET value has been created and shared.
profanity_filter_timestamp The current time (UTC) as a unix timestamp. If this differs by over an hour, an error will be returned.

Each response is a PHP serialized variable. Errors are WP_Error objects. If the response cannot be decoded, it is treated as an error as Profanity Filter probably isn’t installed.

Error Code Description
nosub The setting to turn on the communication API has not been turned on.
wrongversion The version parameter does not match the version stored in the plugin.
missingparam A required parameter is missing from the request. The name of the parameter will be returned as the error’s data.
invalid A parameter is not valid. The name of the parameter will be returned as the error’s data.
synchronize The timestamp differs by over an hour. A correct timestamp will be returned as the error’s data. A forum should not try again if this is given when using the new value.

The missingparam error must always be returned first. All other errors can be returned in any order. Only one error should be returned per request.

Request types:

subscribe
The host sends a verify request to the URL with the default parameters plus profanity_filter_requested set to the IP address that the subscribe request was sent from. If the response is not a serialized boolean true, an invalid error is returned with the data profanity_filter_url. If the request is valid, the host stores the profanity_filter_secret parameter in its subscription data and the current data is returned. If the host does not allow subscriptions, a nosub error is returned.

verify
Simply return boolean true if you are subscribed to the profanity_filter_url and false if you are not after verifying that the key is valid. profanity_filter_requested should be stored, along with the IP address that the verify request was sent from if the request is invalid. Note that profanity_filter_requested may be omitted if the request is not new.

update
An additional parameter, profanity_filter_data will contain the data that has been updated. Simply update the data after checking for the request’s validity. A response of a boolean true means success.

unsubscribe
Do not send future updates to the URL after checking the request’s validity. The return value is not important.

Advertisements