Waegis

Register | Log In

Overview

Waegis exposes an open API for development and lets developers use this API in order to build client libraries and plug-ins for different content providers.

Our API is a RESTful API and is completely written on top of Windows Communication Foundation (WCF) 3.5 which is a part of Microsoft .NET Framework 3.5.

The structure of API calls is based on unique URIs that are built from some user parameters along HTTP PUT methods. We support XML format for our API calls and you need to put some XML structures on our servers to receive XML structures in response.

Concepts

To work with our API, you need to be aware of some basic concepts that we apply in our API and some common concepts in spam filtering terminology. Here we describe them shortly:

• Spam is the bad content that we try to block.
• Ham is opposite to spam and is the legitimate content.
• API key is a unique string value that we give to our users and they can use this key in order to use our API. This API key is private for user and is used frequently in our service to build REST URI templates.
• Site instance is a URL that refers to a part of a site. We use site instance URLs to distinguish the independent parts of a site like the homepages of multiple blogs on a single site or homepages of different forums.

Structures

We have three structures in our API. Two structures are used by our clients and the third one is used by our API as the response structure of our methods.

Each structure has some properties that must be represented as XML elements. Some properties are required and must be provided while some properties are optional. Of course, we strongly recommend you to provide more information for us to get the best result from our service. The order of properties (XML elements) does matter for us and can cause errors on client-side, so take care about the order of properties as well.

instance

instance is a structure that represents a site instance and has a single required property.

• url (required): The URL of the site instance that you want to define.

So an example of an instance structure is this:

post

post is a structure that represents a post on your site which can be a comment, trackback, pingback, forum post, wiki post, contact form data, email or similar stuff.

This structure has ten properties including some required properties as well as some optional properties.

• instance (required): The unique URL of the site instance associated with this part of your site. This is same as what you have used to initialize your site instance.
• permalink (required): The unique URL of the parent post or current post. For example, for a blog comment this is the permalink of the parent blog post or for a forum post this is the URL of the parent thread.
• postType (required): Specifies the type of your post and can be set to one of comment, trackback, pingback, forum, contact, wiki or email values. Other values are acceptable but can have an effect on the quality of your end result. These values are case-insensitive for us.
• body (required): The body of your post or its main content.
• title (optional): The title of your post.
• authorName (optional): The author's name.
• authorUrl (optional): The author's URL.
• authorEmail (optional): The author's email.
• referrer (optional): The HTTP referrer of the page where user has entered the content. This is equal to HTTP_REFERER header parameter.
• clientIP (optional): The IP of the client who has left the content.
• clientAgent (optional): The user agent of the client who has left the content.

In fact, this is the only structure in Waegis API with optional properties. By the way, we strongly recommend you to provide more information for our service in order to get the best result, so try to fill optional properties with correct data if you can. Of course, this depends on the type of post. For example, a blog post may have a URL for author as well as an email but a forum post usually does not have these characteristics.

Here is an example of a post structure:

Note 1: You must represent the properties in the same order as what we have listed here. If you reorder them, then you'll receive an error.

Note 2: You can eliminate optional properties from the structure, so here is a post structure without some optional properties:

result

The last structure that plays a role in Waegis API is result. This structure is what you get from our service and you don't need to build it. Instead, you need to parse it to get your desire outcome. result has two required properties.

• status (required): It is always set to one of success or failure values. success means that your operation has been successful and you can get the result from the message parameter. failure means that your operation has failed and you can find the reason in the message parameter.
• message (required): This is a string value that describes your result. For example, a valid value for initialize method means that your site instance is valid and you can use it and a ham value for check method means that your post is legitimate content.

So here is an example of the result structure retrieved from the initialize method:

Methods

Waegis API provides four methods through a RESTful structure to let you initialize your site instances, check and evaluate your posts for being spam, and also allows you to report ham and spam posts to us if we have done something wrong.

The RESTful API is based on unique URIs and what makes our method URIs unique is your API key. The base part of our service method URI is api.waegis.com/web/{api version}/{api key} following with the method name. This URI is built of some static parameters as well as two dynamic parameters. {api version} is the version of Waegis API that you want to use. Currently there is only one version (1.0) to use. The other parameter is {api key} that is a private string value that you can retrieve from your account on Waegis site and should keep it private.

To use our methods, you need to use a client and HTTP PUT verb in order to put the appropriate XML structures (described above) on the appropriate URIs on our service.

initialize (api.waegis.com/web/1.0/{api key}/initialize)

This method is one of the main two methods that play an important role in Waegis API workflow. initialize method gets an instance structure as its parameter and returns a value specifying if your site instance is valid or invalid.

If your site instance is not initialized before, then this method initializes the instance and lets you start using it as well. If you have reached to the maximum limitations for your account then this method returns an invalid response to let you know. This rarely happens because we have high limitations for our users. However, if you have a big site that may exceed 200 site instances and 150000 monthly API calls, then you can contact us to lower your limitations with no extra charge.

The common responses from this method are:

• valid: It means that your site instance is valid and you can have a call to other three methods with this site instance. Of course, this is just for one time and this value may be different for future calls.
• invalid: It means that your site instance is invalid. There are some common reasons like being banned by Waegis security system, hitting the maximum limitation for the number of monthly API calls or site instances or using a wrong API key.

By the way, this is a very important method.

check (api.waegis.com/web/1.0/{api key}/check)

The second common method for Waegis API is check and of course this is the main method that all our clients are looking for. check method simply checks an incoming post to mark it as spam or ham.

This method gets a post structure as parameter and returns one of the following two values:

• spam: Incoming content is spam.
• ham: Incoming content is ham (legitimate).

There may be some reasons to get a failure for this method but a call to initialize method can prevent most of them.

Note: There is a logical upper-bound limit for the size of post structures that you can put on our API, so if your post structure is extremely large (the overall size of XML structure) then take care about this point.

report-ham (api.waegis.com/web/1.0/{api key}/report-ham)

You may experience some wrong results from us such as a legitimate content (ham) that is marked as spam (false-positive). Waegis is built on self-learning methods, so you can correct its mind by reporting this fault.

report-ham is a method that gets a post structure as parameter and applies it to correct the mistake. The common result of this method is a simple text that thanks you for your help.

report-spam (api.waegis.com/web/1.0/{api key}/report-spam)

Like report-ham method, there may be some cases when we mark a spam post as ham incorrectly (false-negative). You can also help us here and report this mistake via report-spam method to let Waegis learn from its mistakes.

report-spam gets a post structure as well and applies it to avoid further mistakes. The common response for this method is similar to the respone for report-ham which is a thanksgiving text.

Workflow

We have a recommended workflow for calling our API for developers to use in their libraries and applications. We strongly recommend you to follow the same workflow to get the best experience. This workflow is very simple and has a few steps. Follow this workflow each and every time that you received a new post and wanted to check it.

• Find the appropriate site instance.
• Call initialize method with the API key and the site instance.
• If initialization failed, then notify the user in the best form that you can.
• If initialization succeeded, then call check method by passing the relevant post structure.

This is a very simple workflow to implement. You can also provide separate mechanisms for end users to report hams and spams via report-ham and report-spam methods.

User Agent

We recommend you to define your client agent with a special pattern as you see (simply copy/paste this pattern and replace the appropriate values to make sure about everything):

Client Name [Version] / Application Name [Version] / Waegis [Version]

For example, for a client library called "Waegis .NET" version 1.0 and a plug-in for BlogEngine.NET version 1.4, and current version of Waegis API (1.0), you can end up with something like this:

Waegis .NET 1.0 / BlogEngine.NET 1.4 / Waegis 1.0

Important Notes

We have just some latest points for you and hope that you read and apply them carefully in order to gain the best quality from our service:

• Each call to any of the check, report-ham and report-spam methods in the API will be calculated as a single API call. But there is also a separate system that counts your calls to initialize method, and if you exceed from a maximum number, then your account will be locked. However, if you have a site with extremely high API usage, then you can contact us to extend your account limitations for free.
• Our recommendation is to auto-moderate all posts if you experienced any problem with our services like a downtime or any unexpected issue.
• When a post is marked as spam, it's much better to store it locally somewhere for a short while (i.e. 10 days) to let users be able to moderate and report our faults.
• There are some powerful security mechanisms designed to prevent possible attacks to our service and illegal use of the API. If you go wrong with anything, then you may get blocked with these mechanisms temporary or permanently. If you think that you've been blocked with no reason, then just drop us a line with some details about your account and we'll start digging into the problem.
• Always take care about the upper-bound limit of request size for our service API calls. It may reject your large requests.
• We don't care about any other spam filtering mechanism that you may use on your client-side and have no advice to keep it or not. We leave this to yourself to decide but keep in mind that we have built Waegis in a way that it works independently as a powerful spam filtering service, so you can simply trust on Waegis to block your spams.
• In all stages of the development and usage, try to keep API key as a private parameter. If you need an API key for development, just contact us.
• Do not report back our results to ourselves. Some developers may want to help us to learn from our results, so just report back anything that they receive from our service automatically. This is just a waste of your API calls because we already have taken care of this.

If you have built anything with or for Waegis API or if you have any problems or questions about Waegis API, we will be glad to hear from you, so just contact us.

© 2008 - 2009 Waegis.com. All rights reserved.

Privacy Policy | Terms of Service