API Specification¶

Overview¶

The following document describes the RESTful API for the tweetworks platform. The document specifies the general aspects of the API plus a detail of the available requests with their corresponding responses.

General aspects¶

The API is a RESTful service, thus implemented over plain HTTP. The information is sent as regular HTTP parameters plus some special HTTP headers on the request and response that are common to the protocol as a whole.

The API is designed to provide support on several formats to render the response. As of now we're only returning JSON, but implementations for:

XML
JSONP

are expected for the near future.

HTTP headers¶

Request headers

So far API calls must include the following header:

x-tw-TWID: a unique identifier of the instance making the API call. An instance is associated on the server to a user session. Thus, for a mobile application (such as iPhone) an instance would be each unique device. For a web 3rd party application, an instance would be each different web session on that application.
x-tw-client-identifier: an identifier of the application that is making the request. Each client application or 3rd party developer get assigned an identifier and a key to properly authenticate themselves as an authorized consumer of the API. For instance, the iPhone application may identify itself as "IPHONE"
x-tw-token: a token derived of hashing with a sha1 algorithm the following signature #url--#key where #url is the full url of the request and #key is the secret key assigned to this client application. The server internally looks up for the key associated with the given x-tw-client-identifier and then performs a similar hash at his side to validate the request

Response headers

All responses include the following status headers:

x-tw-statusCode: a numeric code indicating the status of the response (basically, whether the request was successfully processed or not)
x-tw-status: a string, human readable identifier for the status
x-tw-statusMessage: a descriptive message, most commonly containing the error description for the error cases or empty for successful cases.

Available status codes are:

200 - OK
201 - VALIDATION_ERROR
300 - UNAUTHORIZED_CLIENT
301 - NEEDS_LOGIN
400 - WRONG_REQUEST

Request common structure¶

All request have a common path structure that includes:

The API domain. That will depend on the deployment of the api instance you are connecting to. We will assume the default api.tweetworks.com all throughout this document
- On development scenarios, this may also include an extra path element to indicate which environment you want to test against (e.g. http://api.tweetworks.com/api_test.php/ to point to the test environment)
"module" and "action": module and action are the first two items on the request path after the domain and are used to identify the logic that needs to process the request
optionally a set of parameters, almost always passed among the query string of the request.

In most of the examples below, the parameters are shown as GET parameters (i.e. sent on the query string). However, all API calls support both GET and POST HTTP methods, with the exception of calls that include a multi-part post (i.e. a request that includes files). In those cases, clearly only POST is supported.

For some calls, specially the ones that create or modify server data, the parameters must be sent inside a "data" envelope. For these calls, is most natural to receive the request by POST method, however GET is also supported.

So, a sample API request for user registration may be:

http://api.tweetworks.com/user/signup?data[name]=foo&data[password]=bar...

Response Objects¶

Object responses for the same kind of entity are the same across all API calls. For some entities, more than one "depth level" is available. Not every depth level is needed for all entities. The client does not need to specify the required depth level, as it depends on the call itself. When not specified, the calls return a "NORMAL" depth level response. Possible depth levels are: