Our API is based on REST architecture which is resource oriented and uses built in features of HTTP, like authentication, verbs and response codes. All request and response bodies are JSON encoded, including error responses.
Any HTTP client can be used to communicate with our API.

Authentification

This API is authenticated using HTTP Basic Auth over HTTPS. Any request made over HTTP will fail with a 404 error code.
You have to use your email as user and a RBL Watcher API key as password.
You can create and revoke API keys here : Manage yours API keys

Here is an example of a basic API Call using Curl :

$ curl -u email:api_key https://rblwatcher.com/api/v1/ping

Requests

The base URL of the API is : https://rblwatcher.com/api/v1

JSON Bodies

All POST, PUT, PATCH requests have JSON encoded bodies (when body is needed) and must have have content type of application/json.

HTTP Verbs

We use standard HTTP verbs to indicate intent of a request:

  • GET - To retrieve a resource or a collection of resources
  • POST - To create a resource
  • PATCH - To modify a resource
  • PUT - To set a resource
  • DELETE - To delete a resource

Responses

All response bodies are JSON encoded.

A single resource is represented as a JSON object:

{
    "field1": "value",
    "field2": true,
    "field3": []
}

A collection of resources is represented as a JSON array of objects :

[
    {
        "field1": "value",
        "field2": true,
        "field3": []
    },
    {
        "field1": "another value",
        "field2": false,
        "field3": []
    }
]

Timestamps are in UTC

lastcheck: "Thu Oct 10 08:30:03 UTC 2013"

HTTP Status Codes

Success codes :

  • 200 OK - Request succeeded. Response included
  • 201 Created
  • 204 No Content - Request succeeded, but no response body

Error codes :

  • 400 Bad Request - Could not parse request
  • 401 Unauthorized - No authentication credentials provided or authentication failed
  • 403 Forbidden - Authenticated user does not have access
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error
  • 429 Too Many Requests - Request rejected due to rate limiting
  • 500, 501, 502, 503, etc - An internal server error occured

Errors

All errors (400, 401, 403, 500, 501,... etc) will be returned with a JSON object in the body and a application/json content type.
The JSON oject contains two fields :

  • code : An integer representing an error code (dérived from HTTP error code)
  • msg : A string giving information about the error

Here is an example :

{
    "code": 4041
    "msg": "IP x.x.x.x is not watched (yet) by RBL Watcher"
}

Rate limits

Our API is limited to 1 calls per seconds.
If the rate limit is hit, the API will return an 429 Too Many Requests HTTP status code.

PING

This ressource helps you to tests connectivity and authentification.

Request :

GET /api/v1/ping

Reply :

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 4
pong

Account

This section list all actions concerning your account.

Email alerts

Enable/Disable email alerts when status of an IP changes.
Note that by default email alerts are enabled

Request :

PUT /api/v1/account/enableEmailAlerts/true|false

Reply :

HTTP 204 No Content
Content-Length: 0
                

IP

This section list all actions concerning IP addresses.

All IP

Return all your IP watched by RBL Watcher

Request :

GET /api/v1/ip/all

Reply :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 131
{"ip":["46.105.152.28","78.41.233.83","91.121.228.128","91.121.228.135","46.105.152.20","8.8.8.8","178.33.223.35","46.105.45.231"]}

Blacklisted IP

Return all your IP which are blacklisted on RBL

Request :

GET /api/v1/ip/blacklisted

Reply :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 23
{"ip":["78.41.233.83"]}

Not Blacklisted IP

Return all your IP which are not blacklisted on RBL

Request :

GET /api/v1/ip/notblacklisted

Reply :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 116
{"ip":["46.105.152.28","91.121.228.128","91.121.228.135","46.105.152.20","8.8.8.8","178.33.223.35","46.105.45.231"]}

IP details

Details about an IP

Request :

GET /api/v1/ip/78.41.233.83

Reply :

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 228
{
    "ip" : "78.41.233.83",
    "isBlacklisted" : true,
    "lastcheck" : "Tue Dec 17 10:27:16 CEST 2013",
    "reverse" : "3.mxout.protecmail.com",
    "blacklsitedIn" : [
        {
            "desc" : "spam.spamrats.com",
            "name" : "spam.spamrats.com",
            "url" : "http://www.spamrats.com/"
        }
    ]
}

Add an IP

Add an IP to your RBL Watcher watchlist

Request :

POST /api/v1/ip/213.186.33.56

Reply :

HTTP/1.1 201 Created
Content-Length: 0

                

As you can see if request succed, the HTTP response body is empty.

Here is en example if an error (IP already on your watchlist) occured :

Request :

POST /api/v1/ip/213.186.33.56

Reply :

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Content-Length: 64
{"code":4221,"msg":"213.186.33.56 is already on your watchlist"}

Remove an IP

Remove an IP from your RBL Watcher watchlist

Request :

DELETE /api/v1/ip/213.186.33.56

Reply :

HTTP/1.1 200 OK
Content-Length: 0