Although I haven’t used it yet, I’ve been watching Akismet with interest. Their goal is to fight comment and trackback spam, free for personal use and a fee for commercial use. When Matt first announced this service I downloaded the WordPress Plugin just to look through the code to see what the API looked like.
My interest was rekindled with the announcement of API docs for Akismet. The API is pretty simple (good) and called via REST. Then I wandered over to their Spam Stopper email list to see what sort items were being discussed. One of the first emails I came across had a reasonable question:
The API documentation says of the comment-check function :
“This call returns either “true” or “false” as the body content.”
I have been assuming that “false” means the comment *is* spam – is this correct ?
I thought this was kind of odd, so I went back and checked the docs again. Sure enough that was all the docs said about return values for comment-check. Matt provided a quick reply though:
That would be the problem. 🙂
True = this is spam
False = this is not spam
So the lesson learned here is to remember to document everything when it comes to your API. This reminds me a something I read somewhere: don’t write so that you can be understood, write so that you can’t be missunderstood.
None of this is meant as a strike against Matt, anything that helps reduce the amount spam going around is a good thing. The docs were also listed as a first draft, so I’m sure they will get additional refinement as time goes on.