Global

The information in this page applies to all interactions with the API.

Request Format

Headers

The following headers are required for each request, unless otherwise noted:

• User-Agent: The client library that sent the request, in the following format: Client Library Name | version-as-a-float. For example, version 0.1.2 of the Java library would use the following User-Agent: java2cloud | 0.1.2.
• Authorization: The username and secret for the account, encoded as per Basic Authentication; namely, the string "Basic", followed by a space, followed by a Base64 encoding of "username:secret".
• From: The device address of the device making the request.

Requests with a body (PUT/POST requests) require the following headers, as well:

• Content-Type: a resource-specific content type. All follow the format "resource/encoding", where resource is the resource type in lowercase, and encoding is the output encoding (for version 1, this will always be "json").
• Content-Length: the length of the request, in bytes.

The following headers are optional:

• API-Version: The API version the request is expecting the server to be running. If not set, the latest version of the API is assumed.
• Accept: The resource and encoding the library expects in the response. If not set, any resource type is permissable, and the encoding will be in JSON.

Response Format

Code

The API uses descriptive response codes when responding to requests. The following response codes are used:

Success

• 200 OK: The request was fulfilled successfully; no errors.
• 201 Created: The request was fulfilled successfully and resulted in the creation of a new resource.

Request Failure

• 400 Bad Request: The request was not correctly formed. Retrying will not solve the problem.
• 401 Unauthorized: The authentication on the request was missing or invalid.
• 402 Payment Required: The authorising account's subscription has expired, and needs to be renewed to resume using the service.
• 403 Forbidden: The authenticating user does not have permission to access the requested resource.
• 404 Not Found: The endpoint or resource requested could not be found.
• 405 Method Not Found: The method of access (POST/PUT/GET/DELETE) is not supported on the resource. This does not make any assertion as to whether or not the resource can be found.
• 406 Not Acceptable: The API version specified in the request's API-Version header is no longer supported or the resource/encoding combination specified by the request's Accept header is not supported.
• 409 Conflict: The request was correctly formed, but the information provided in it is not acceptable.

Server Failure

• 500 Internal Server Error: Something went wrong on the server. The request should not be retried; the development team should be notified of the error.
• 503 Service Unavailable: The server is not currently available. The request should be retried using exponential backoff.

Body

Response bodies all conform to the same basic structure.

{
  "code": int,
  "msg": string
}

code is a copy of the HTTP response code that was issued with the response, in the form of an integer. It is duplicated to make it simpler to include it when passing around responses.

msg is a human-readable explanation of the response code in English. For API v1, we do not offer internationalisation of the msg property.

In addition to code and msg, responses will have properties unique to the resource they describe. The following properties are valid:

• accounts: for requests against Account resources
• devices: for requests against Device resources
• links: for requests against Link resources
• notifications: for requests against Notification resources
• subscriptions: for requests against Subscription resources
• users: for requests against User resources

These resource-specific properties will be arrays of JSON objects, the specifics of which depends on the resource type. Example responses for each may be found in the resource's page.

Finally, each request may return an array of error objects.

{
  "code": int,
  "msg": string,
  "errors" [
    {
      "code": int,
      "item": int,
      "field": string
    }
  ]
}

Errors

The error.code field will consist of an integer representing an error specific enough to be remedied with a single action. The error.item field will only be present in errors thrown for methods that allow multiple input items. It will denote the position in the uploaded array of input items that the error was encountered. The error.field field will consist of the field that triggered the error.

The following errors may be returned for all or nearly all requests:

Status	Code	Field	Explanation
401	ERROR_MISSING_PARAM	headers.authorization	The Authorization header was missing.
401	ERROR_INVALID_FORMAT	headers.authorization	The Authorization header was not encoded as per Basic Authentication.
401	ERROR_INVALID_VALUE	headers.authorization	The Authorization header specified incorrect information.
401	ERROR_NOT_FOUND	headers.authorization.username	The username specified in the Authorization header does not belong to a user.
400	ERROR_MISSING_PARAM	headers.from	The From header was not set.
400	ERROR_INVALID_FORMAT	headers.from	The From header was not an integer.
400	ERROR_NOT_FOUND	headers.from	The ID specified in the From header does not correspond to a known device.
400	ERROR_ACCESS_DENIED	headers.from	The From header is set to the ID of a device the authenticating user doesn't own.
503			The server is temporarily unavailable. The request should be retried after the number of seconds specified in the Retry-After header.
404			The requested endpoint does not exist.
405			The HTTP method used to access the endpoint is not accepted.

Headers

All responses will have the following headers:

• Content-Type: a resource-specific content type. All follow the format "resource/encoding", where resource is the resource type in lowercase, and encoding is the output encoding (for version 1, this will always be "json").
• Last-Modified: the date the resource was last modified.
• API-Version: the version of the API that generated the response.

Also, some responses may carry the following headers:

• Retry-After: If the server is unavailable, this will let the client know how long (in seconds) to wait before retrying the request. Clients should respect this header.
• Warning: a warning for the end user. It may be that their client is out of date and they should upgrade, or it may be something else. Consult the Warnings documentation for the possible codes and their meanings.