Blog::Spam::API - A description of Blog-Spam API.
This document discusses the API which is presented by the Blog::Spam::Server to
remote clients via XML::RPC.
The server itself has two APIs:
- The XML::RPC API
- This is the API which is presented to remote callers.
- The Plugin API
- The API that the server itself uses, and which plugins must conform to, in
order to be both used and useful. The internal plugin API is documented
and demonstrated in the the sample plugin.
The Blog::Spam::Server exposes several methods to clients via XML::RPC.
The following methods are documented <http://api.blogspam.net/> as being
available:
- testComment
- This is the method which is used to test a submitted comment from a blog
or server. Given a structure containing information about a single comment
submission it will return a result of either "spam" or
"ok".
- getPlugins
- This returns the names of the internal plugins we use - it is used such
that a remote machine may selectively disable some of them.
- getStats
- Return the number of spam vs. non-spam comments which have been submitted
by the current site.
- classifyComment
- If a previous "testComment" invocation returned the wrong result
then this method allows it to be reset.
Each of these methods will be discussed in order of importance, and additional
documentation is available online <http://api.blogspam.net/>.
The testComment method has the following XML-RPC signature:
string testComment( struct );
This means the method takes a "struct" as an argument, and returns a
string. In Perl terms the struct is a hash.
When calling this method the hash of options may contain the following keys:
- agent
- The user-agent of the submitting browser, if any.
- comment
- The body of the comment the remote user submitted.
- email
- The email address submitted along with the comment.
- fail
- If this key is present your comment will always be returned as SPAM;
useful for testing if nothing else. This handling is implemented by the
plugin Blog::Spam::Plugin::fail.
- ip
- The IP address the comment was submitted from.
- name
- The name of the comment submitter, if any.
- subject
- The subject the comment submitter chose, if any.
- site
- A HTTP link to your site which received the comment submission. In
most cases using $ENV{'SERVER_NAME'} is the correct thing to do.
- options
- Customization options for the testing process, discussed in the section
TESTING OPTIONS.
The only mandatory structure members are "comment" and "ip",
the rest are optional but recommended.
The return value from this method will either be "OK", or
"SPAM".
Optionally a reason may be returned in the case a comment is judged as SPAM, for
example:
SPAM:I don't like comments submitted before 9AM.
The classifyComment method has the following XML-RPC signature:
string classifyComment( struct );
This means the method takes a "struct" as an argument, and returns a
string. In Perl terms the struct is a hash.
The keys to this method are identical to those in the testComment method - the
only difference is that an additional key, "train", is recognised
and it is mandatory:
- train Either "ok" or "spam" to train the comment
appopriately.
If the comment was permitted to pass, but should have been rejected as SPAM set
the train parameter to "spam", if it was rejected and should not
have been set the train parameter to "ok".
The getPlugins method has the following XML-RPC signature:
array getPlugins( );
This means the method takes no arguments, and returns an array.
This method does nothing more than return the names of each of the plugins which
the server has loaded.
These plugins are modules beneath the Blog::Spam::Plugin:: namespace, and their
names are the module names minus the prefix.
The getStats method has the following XML-RPC signature:
struct getStats( string );
This method returns a struct and takes a string as its only argument.
This method returns a hash containing two keys "OK" and
"SPAM". These keys will have statistics for the given domain - or
global statistics if the method is passed a zero-length string.
Note: The string here should match that given as the "site" key
to the method testComment - as that is how sites are identified.
When a comment is submitted for testing, via the testComment XML::RPC method it
may have an "options" key in the structure submitted.
The options string allows the various tests to be tweaked or changed from their
default behaviours.
This option string should consist of comma-separated tokens.
The permissible values are:
whitelist=1.2.3.0/24 - Whitelist the given IP / CIDR range.
blacklist=1.2.3.3/28 - Blacklist the given IP / CIDR range.
exclude=plugin - Don't run the plugin with name "plugin". (You may find a list of plugins via the getPlugins() method.)
mandatory=subject,email - Specify the given field should always be present.
max-links=20 - The maximum number of URLs, as used by L<Blog::Spam::Plugin::loadsalinks>
min-size=1024 - Minimum body size, as used by L<Blog::Spam::Plugin::size>.
min-words=4 - Minimum word count, as used by L<Blog::Spam::Plugin::wordcount>.
max-size=2k - Maximum body size, as used by L<Blog::Spam::Plugin::size>.
fail - Always return "SPAM".
These options may be repeated, for example the following is a valid value for
the "options" setting:
mandatory=subject,mandatory=name,whitelist=1.2.3.4,exclude=surbl
That example will:
1. Make the "subject" field mandatory.
2. Makes the "name" field mandatory.
3. Whitelists any comment(s) submitted from the IP 1.2.3.4
4. Causes the server to not run the surbl plugin.
- Steve Kemp
- http://www.steve.org.uk/
Copyright (c) 2008-2010 by Steve Kemp. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself. The LICENSE file contains the full text of the
license.