Posting documentation

This covers the process of posting an error from your website into Arecibo. There are two main methods of sending an error to Arecibo:

• a HTTP post
• a HTTPS post (requires paid account)
• or an email

There are some example clients that allow posting of data into Arecibo team. These can be checked out of SVN as a read-only version at:

svn co http://arecibo.svn.beanstalkapp.com/clients/

HTTP Post

The URL for version 1 of the API is:

http://www.areciboapp.com/v/1/

When the next major release of Arecibo API happens, we will increment the URL to /v/2/, leaving the /v/1/ active. This will allow clients to upgrade as needed.

The method for sending an error is simple, a HTTP POST to the above URL containing the variables set out in the documentation.

Notes

• HTTP GET requests will be ignored, only POST
• The only required variable is the Arecibo API key
• If possible set a timeout in your posting client (say 10 seconds)

Example in Python

Sending a HTTP POST in Python is easy using the urllib module. The most minimal request that can be sent just contains the API key, so let's send that as a first example:

Python 2.4.4 (#1, Feb 18 2007, 22:11:27) 
[GCC 4.0.1 (Apple Computer, Inc. build 5250)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import urllib
>>> data = {"account":"youraccountnumber"}
>>> encoded = urllib.urlencode(data)
>>> urllib.urlopen("http://www.areciboapp.com/v/1/", encoded).read()
'Error recorded'

If the request is successful, a HTTP status of 200 will be returned.

The only thing you can really do wrong with this is get the API key wrong, Arecibo will do its best to record the error no matter what the error. If you've got some things in the POST that are wrong besides the API key, then Arecibo will simply log them on error. Sending a false API key will give you:

>>> data = {"account":"wrongaccountnumber"}
>>> encoded = urllib.urlencode(data)
>>> urllib.urlopen("http://www.areciboapp.com/v/1/", encoded).read()
'Problem recording the error: Account wrongaccountnumber does not exist.'

The request will also return a HTTP status of 500.

Once you've established how to make your error post, you can proceed to add in more variables. Here we are sending an error including the priority, status and some extra information in the msg:

>>> data = {"account":"youraccountnumber", "status": 403, "priority": 1,
... "msg": "Someone tried to access /secure without the appropriate authorization"}
>>> encoded = urllib.urlencode(data)
>>> urllib.urlopen("http://www.areciboapp.com/v/1/", encoded).read()
'Error recorded'

For more detailed and full examples on how to do a such a POST, please see the Python, Ruby or JavaScript libraries. For example the Python library does UTF-8 encoding, checks for required variables and sets time outs to provide leaving sockets open.

HTTPS Post

The URL for version 1 of the API is:

https://www.areciboapp.com/v/1/

The rest of the API for Arecibo is the same, however you will require a paid account.

This will require https support to be available in the client you are using. Whilst this is available for all modern browsers, the server side support is more variable. You should refer to documentation for your servers environment for more information.

Please test a post first to check it is correctly supported, for example in Python:

>>> from httplib import HTTPSConnection

If no error is raised, HTTPS is supported.

Email

The email address for posting emails is:

arecibo@clearwind.ca

Emails are periodically received from this address and posted into Arecibo. The only thing that matters is the body of the email, which has to be in plain text.

The body should contain a dictionary (or hash) that has been turned into a JSON string. The dictionary contains the key value pairings of the error. An example email look like this:

To: arecibo@clearwind.ca
From: admin@yoursite.com
Subject: Site Error    

{"status": "403", "account": "youraccountnumber", 
"uid": "127", "url": "http://sampleapp.org", 
"ip": "127.0.0.1"}

There is no notification back to the sender that occurs on receiving an email, meaning that it can be a little harder to test, so we recommend taking a little more time with email generation. If you think your emails are valid, but don't seem to be received, please drop us a line (including an example) and we'll take a look.

Notes

• The email parser looks for the last } in the email body and assumes everything up to that is the JSON string, thus ignoring any "signatures" added by mail clients or servers. Any signatures that add in a } would cause a problem for Arecibo.
• An invalid JSON string will be rejected without notification, so please test that your integration works successfully.
• The email processing queue is likely to be slower than HTTP, but does have the advantage of being more fault tolerant.

Notes for client authors

Some notes if you are integrating your application into Arecibo.

• Where possible, set a timeout for your application posting to Arecibo, should Arecibo not be available, you do not want this to affect your site.
• Make sure your client library is robust, so that an error posting to Arecibo - either on your end formatting the data or on Arecibo's end - does not cause more errors. In the example Plone integrations when it cannot write to Arecibo because of some error, it logs to the local log file as a place of last resort.
• The more information you can pass the better, generally, however we've found some errors that get continually reported may not be useful. So for example we ignore a 404 that might occur on: favicon.ico or robots.txt in the example integrations. If there are errors that just going to occur regularly, either don't send them or set them as very low priority.

Other API's

As other API's become available, we will document them here. If you have any suggestions for specific API's you'd like to see, let us know.