This API is very similar to and heavily influenced by the Twitter API. Thank you, Twitter for showing us the light. 🙂
All API methods require authentication. All responses are relative to the context of the authenticating user. For example, an attempt to retrieve information for a program not managed by the user will fail.
HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth, use your username (email address) as the username component.
The API attempts to conform to the design principles of Representational State Transfer (REST). This document notes which formats are available for each method.
Some API methods accept parameters, some of which are required.
There is one special parameter in the API:
- Callback: Used only when requesting JSON formatted responses, this parameter wraps your response in a callback method of your choice. For example, appending &callback=myFancyFunction to your request will result in a response body of: myFancyFunction(…). Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.
Methods to retrieve data from the API require an HTTP GET request. Methods that submit, change, or destroy data require either a HTTP POST or a WebDAV PUT. An HTTP DELETE request is also accepted for methods that remove media files. All API Methods require particular HTTP and/or WebDAV methods. Invalid HTTP/WebDAV requests will return an error.
Where noted, some API methods will require specific HTTP headers sent by the client and/or return special HTTP header responses to the client.
HTTP status codes
The API attempts to return appropriate HTTP status codes for every request
- 200 OK: we’re good to go.
- 201 Created: success for WebDAV methods only.
- 304 Not Modified: there was no new data to return.
- 400 Bad Request: your request is invalid, and we’ll return an error message that tells you why.
- 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided are incorrect.
- 403 Forbidden: you are not authorized to access what was requested.
- 404 Not Found: request is either not found or no longer exists.
- 500 Internal Server Error: something went wrong on the server, not your fault.
- 503 Service Unavailable: Service is currently offline for maintenance.
When the API returns error messages, it does so in your requested format.
<?xml version=”1.0″ encoding=”UTF-8″?>
<error>No programs found.</error>
The API supports UTF-8 encoding.
When requesting XML, the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range may be translated to HTML entities.