You are not logged in.    Login    OpenID    Sign up

Defensio exposes an open, RESTful and asynchronous API!

We're proud to be a contributing member of the Web's ecosystem by providing an open API upon which developers can build their own plug-ins and applications that use the Defensio spam and threat filtering web service.

Defensio API, version 2.0

Defensio is a web service designed to help manage spam and other threats on publicly-accessible social web applications such as blogs. Our simple API exposes a handful of functions which return structured responses, making it as convenient as possible for developers to build highly-usable client apps on top of the Defensio service. It is our hope that the Defensio API becomes an important part of the web's ecosystem -- particularly that part devoted to easing the burden of spam and threats across all types of public social web platforms.

Old API (version 1.2)

Documentation for Defensio API 1.2 can be found here. However, we urge you to develop your application with our new API (version 2.0). Support for 1.x will eventually be deprecated.

PDF Version

Download a PDF version of our API 2.0 documentation; sometimes paper is just more convenient!

Developer Guidelines

The Defensio API (below) describes how applications interface with the Defensio web service, but does not suggest how the API should be used for maximum effectiveness. Below we provide guidelines for developers to help them extract the most benefit from the service, and thus create applications that are maximally powerful for the end-user.

Asynchronous Filtering

Since version 2.0, Defensio supports asynchronous document filtering through its Documents/POST action. It is strongly recommended that you make asynchronous calls to our API instead of synchronous calls. Our filtering engine performs much better when used asynchronously. Moreover, asynchronous calls to our API are fast and non-blocking, which greatly improves your user's experience.

To perform asynchronous requests to Defensio, you have to set async=true when performing Documents/POST requests. It is also recommended that you set a callback URL to which we can POST the result once we are done processing your request. The callback URL can be set through the async-callback parameter.

Sending Information to Defensio

In order to obtain the best possible accuracy from us, you should provide us with as much information as possible when performing Documents/POST requests. Although not all parameters are required, you should send as much information as you possibly can.

Also make sure that the information you send us is exact and in the right format.

This makes a world of difference in accuracy.

Sorting by Spaminess

One of Defensio's most valuable features is its ability to provide a mathematically meaningful and consistent spaminess value for each comment it processes through the Documents/POST action. We strongly recommend (almost to the point of insisting) that this function's spaminess return value be used in applications as the primary way to sort a list of spam messages, thus making it trivially easy for users to locate false-positives amongst their spam.

Spaminess might further (at the developer's option) be used in conjunction with a color gradient to provide a simple visual cue for the user in regards the spaminess range of each comment. Also, if the sheer volume of comment spam is onerous on the user, the developer might consider allowing users to specify a spaminess threshold above which "obvious" spam messages are hidden. We have implemented this in the Wordpress plugin , which you might want to use as a reference implementation.

Retraining

Client applications should (again, strongly recommended or performance will greatly suffer) provide the ability for the user to identify and signal to our servers the presence of erroneous spam/ham filtering. The retraining action Documents/PUT are provided to this end.

By informing our servers of such errors, users can contribute to a personalized learning effect on the filter's performance -- this means that the only way for a user to experience improved performance over time, is by correcting the filter when it goes astray. Developers should keep in mind that in order to use these functions they must store, on the client-side, the comment signature returned by the Documents/POST action.

Announcing Content

To help personalize and populate the filter, every time a new article (e.g. blog post) is posted by the user it should (if feasible) be sent to Defensio's servers using the Documents/POST function with the type parameter set to "article". This will help improve filter performance by training the server with decidedly un-spammy content.

It is also possible and recommended to announce any types of content posted to your website by administrators. Simply set type, author-logged-into and author-trusted their corresponding values.

Trusted Users

If the client application is able to ascertain trusted identity credentials for the individual posting a comment (e.g. a blog's editor or administrator) then the application should pass author-trusted=true to the filter's Documents/POST action. This aids in directing and personalizing filter performance.

OpenID

Defensio supports OpenID in its Documents/POST action since API version 1.2. This new functionality leads to improved filtering accuracy. You are therefore encouraged to implement OpenID in your application and to pass along the information to Defensio whenever possible.

It is important to understand that Defensio does NOT perform any OpenID authentication. It is the responsibility of your application to do so.

Once an OpenID authentication has been properly performed, you can pass the user’s OpenID URL to Defensio through the author-openid parameter of the Documents/POST action. This parameter should only be supplied along author-logged-in=true.

Transparency Through Statistics

We believe that users benefit from full transparency. To that end, developers should leverage Defensio's basic-stats and extended-stats actions in order to provide users with a summary of the filter's performance. At minimum, accuracy should be displayed in a convenient location (if it does not detract from the application's user experience).

Watch the Defensio 2.0 video