Handling responses

A responses sent by the API contain a header and a body. The contents of the header show the status of the request. The body is only defined if a request was successful, and its contents depend on the API action executed.

Please note that the API may also return a HTTP 500 error without any valid API output (no headers and no body) if it encounters an internal error. Be sure to handle this statuscode correctly in your application.

The header contains the following fields:

status An integer status code indicating the request status. Success is indicated with 0. See the documentation of the individual API actions for details on the values that can occur on error.
statusmessage A string containing a message that describes the returned status.
apiversion An integer indicating the version of the API that is used. This will always be 3 for API version 3.
cacheable A boolean that is true if and only if the response can be cached. This is typically true for queries for information, such as for the item/view action, and false for actions that modify data, such as the item/edit action.
timezone A string containing the timezone that is used to display all date/time fields. This is normally equal to the timezone for the current actor, unless specifically overridden.
sessiontimeout If an active session is used for the request, an integer containing the number of seconds after now until the session times out. See Sessions for more information on using sessions.

JSON-encoded responses

Responses are currently always encoded using JSON. The response is a JSON-object containing two fields, header and body. The header field is an object containing the fields present in the header as described above, while the contents of the body depend on the API action called.

The JSON response for a successful API call for an action returning an empty body and having Europe/Amsterdam as timezone for the current actor results in the following JSON:

{
   "header": {
      "status": 0,
      "statusmessage": "OK",
      "apiversion": 3,
      "cacheable": false,
      "timezone": "Europe/Amsterdam"
   },
   "body": {}
}