API concepts

This API is very similar to and heavily influenced by the Twitter API. Thank you Twitter for showing us the light. :)

Concepts

Authentication

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.

RESTful resources

The API attempts to conform to the design principles of Representational State Transfer (REST). This document notes which formats are available for each method.

This API supports the following data formats: XML and JSON.

Parameters

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.

HTTP requests

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.

HTTP headers

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.

Error messages

When the API returns error messages, it does so in your requested format.

Example Output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<hash>
<request>/media/index.xml</request>
<error>No programs found.</error>
</hash>
[/xml]

Encoding

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.