Warning: You are viewing an old version (0.8) of this documentation. We recommend you view the latest version 1.2.

REST API Specification

The Ably REST API provides a way for a wide range of server and client devices to communicate with the Ably service over REST. The REST API does not provide a realtime long-lived connection to Ably, but in all other respects is a simple subset of the full realtime messaging API.

The primary use-case for the REST API is for servers that are part of the back-end of an application such as a web application, that publish messages, issue access tokens (temporary and client-specific) for its various clients, obtain message and presence history and retrieve statistics.

The functional scope of the REST API includes:

  • authentication: authentication to the service as a client, plus creation of tokens for use by other clients;
  • publication of messages;
  • retrieval of message history;
  • retrieval of presence state and presence;
  • retrieval of statistics for application usage.

Whilst use of our REST API directly is fully supported, we instead recommend that customers should use our Ably REST client libraries that support a range of platforms including JavaScript, Java, Python Ruby, .NET, Go, etc. The client libraries are well documented and provide additional features that improve performance and resilience that the REST API cannot deliver on its own, such as automatic re-routing around network problems by using alternative datacenters.

Common API behaviour

General

The REST API defaults to returning results, and expects request bodies, in JSON format. An Accept header is used to specify a specific response format – JSON or an alternative – and the following formats are allowed:

  • application/json: JSON;
  • application/javascript: for JSONP. A callback query parameter is also expected, which defaults simply to “callback”;
  • application/x-msgpack: for MessagePack, the efficient binary serialization format that is similar to JSON, but faster and smaller;
  • text/html: HTML

It is also possible to specify the response format with the format query parameter (with supported values being json, jsonp, msgpack, html). Any Accept header takes precedence over a format parameter.

Similarly, POST requests may contain a request body in JSON or other formats as indicated by a Content-Type header. The supported content types are:

  • application/json: JSON;
  • application/x-msgpack: MessagePack, the efficient binary serialization format that is similar to JSON, but faster and smaller;
  • application/x-www-form-urlencoded: Form-encoded.

Specific request and response data types are documented in the context of each API or route.

A response status code of 20X (200, 201 or 204) indicates success. A successful result will typically provide a response body but certain operations (such as DELETE) may respond with a 204 response and no response body.

All other standard HTTP statusCodes signify an error. Errors from all APIs are returned as an object of the form:

{
  error: {
    code: <ably error code>,
    message: <string>,
    statusCode: <http status code>
  }
}

Additionally, when you may not have access to the response body due to limitations of your HTTP client, we include the following custom Ably headers to work around that problem:

X-Ably-ErrorCode: <ably error code, equivalent to error.code>
X-Ably-ErrorMessage: <string, equivalent to error.message>

The properties of an Ably error are:

code
A specific reason code as defined in the public errors definition, where one is known
statusCode
Where a code is not available, the statusCode provides a generic indication of the nature of the failure and maps to standard HTTP statusCodes
message
The message string is an English language string that aims to provide useful information to the developer. It is not necessarily intended to be an informative string for the end user

Wherever possible, success response bodies contain links, in HATEOS style, to other resources relevant to the response; where these are present these are included as href attributes on the applicable part of the response object.

GET, PUT, POST and DELETE are available in all contexts where they make sense. GET is always idempotent.

Versioning

By default, all requests receive the latest version of the API, which is currently 0.8.

When we make backwards-incompatible API changes to the API, we release new versions. Therefore, we encourage you to explicitly request the version you are interfacing with in all requests using one of the following mechanisms:

1. Include a X-Ably-Version header. Example:

curl https://rest.ably.io/time \
 -H "X-Ably-Version: 0.8"

2. Include the version query string param v. Example:

curl https://rest.ably.io/time?v=0.8

Pagination

REST APIs whose responses may have unbounded size have paginated responses; that is, if a full response to the query could exceed a limit (a default or a limit given as a parameter to the call) the first response contains a subset of the results, and further “pages” of the result are available on subsequent requests. Each response (the initial response and responses to each subsequent request) is accompanied by one or more relative links relating to the current query.

Responses contain one or more of the following relative links:

first
a link to the first page of results for this query. This link also makes the query repeatable; any params that are resolved at query time (for example default values for omitted time-related params) have their resolved values included explicitly in the first link.
current
a stable link to the current page of results.
next
on each page except the last in a paginated result, the next link is a link to the next page of results.

Relative links are presented by default as an RFC 5988 Link HTTP response header; there is a separate Link header for each relative link accompanying the response. The rel types used are first, next and current as specified in the RFC.

A Link header has the format:

Link: <{url}>; rel="{rel}"

where {url} is the URL of the link and {rel} is the relation type.

For example:

Link: <./stats?start=1380794880000&end=1380794881058&limit=100&unit=minute&direction=forwards
&format=json&first_start=1380794880000>; rel="first"

In principle the link URL might be any valid URL but in practice it will always be a relative URL, and it must be interpreted relative to the original query URL. Clients should treat link URLs opaquely; in particular, params (such as first_start in the example above) may be undocumented and unsupported except where a client uses the link URL in its entirety.

Clients that are unable to process response headers may also request an envelope response type.

Control of response content

By default the response body of a query response will contain the requested resource, encoded in the requested format. However, there are also query params that allow the response body to be adjusted to contain only a subset of the representation, or a restructured representation.

The following params are supported:

fields

Specifying ?fields=<field spec>[,<field spec>, ...] returns the representation containing only the specified fields. A field spec is a specifier which is either a single field – in which case the representation contains only that fields’s value – or a dot-separated sequence of fields, in which case the representation contains only the fields matching those given in the field spec at each level in the hierarchy.

Example
curl https://rest.ably.io/stats?fields=channels.peak,intervalId \
     -u "xVLyHw.r7CA9A:wR-O5HrJ5RLnfOZ5Df1irljNMxjyQVU8pgOZILUVYTY"

# Response
[{
    "channels": { "peak": 2 },
    "intervalId": "2015-11-20:15"
}]

flatten

Specifying ?flatten=true will result in a flattened representation, with the returned object structure being flattened into one with a single level of long keys instead of a deep structure. When the results contain array elements, the array index of each element is included as the corresponding component of the result key.

Example
curl https://rest.ably.io/stats?flatten=true&fields=channels.peak,intervalId \
     -u "xVLyHw.r7CA9A:wR-O5HrJ5RLnfOZ5Df1irljNMxjyQVU8pgOZILUVYTY"

# Response
{
    "0.channels.peak": 2,
    "0.intervalId": "2015-11-20:15"
}

select

Specifying ?select=<path spec> returns a representation of the resource containing only the fields that match the given path specification. Like the fields param this permits only specific fields to be obtained, but the path spec may contain wildcard elements, and all matching fields in the representation are returned.

The result is a partially-flattened representation, as a map whose keys are the long keys that match the path spec, and the values are the corresponding values. When the results contain array elements, the array index of each element is included as the corresponding component of the result key.

Example
curl https://rest.ably.io/stats?select=*.channels.* \
     -u "xVLyHw.r7CA9A:wR-O5HrJ5RLnfOZ5Df1irljNMxjyQVU8pgOZILUVYTY"

# Response
[{
    "0.channels.peak": 5,
    "0.channels.min": 1,
    "0.channels.mean": 3,
    "0.channels.opened": 2
}]

Envelope response format

A client that is unable to access response headers or status code can request an envelope response that contains the usual response, plus Link header information and the response status code wrapped in an object as a single response body. This is useful for JSONP and may be useful in other environments. Envelope responses are only supported for JSON, JSONP and HTML formats.

A client requests an envelope response by including an envelope=<format> param in the request.

A JSON envelope response body response for a request with an envelope=json param has the format:

{
    "statusCode": <status code>,
    "response": <result of API call>,
    "rel": {
        "first": <URL>,
        ...
    }
}

where the response member references the API result in the usual format. The rel member, present only in paginated responses, includes each of the rel links associated with the response.

Envelope responses always are always made with a 200 status code; the status of the API request itself must be obtained from the statusCode member of the response body.

Authentication

To understand the REST API it is easiest first to understand the various authentication methods that Ably supports. For a detailed explanation, view the Authentication documentation.

Clients can access Ably, whether using REST or the Realtime service, by two methods, explained briefly below:

Basic Authentication

Using one of the application keys created via the application dashboard, basic authentication provides the simplest method to authenticate with Ably, but has two important limitations:

  • the application key is transmitted over the network as part of a request; therefore it may only be used over TLS (HTTPS or “SSL”) connections. This can be a performance disadvantage in some network environments where long round-trip times are amplified by the SSL handshake.
  • the client using the API must be in possession of the application key, which potentially exposes the key to compromise. For example, it is not advisable to simply embed the key in a script in a public web page.

Usage in HTTP request header

Authorization: Basic <Base64-encoded key>

where <Base64-encoded key> is the full application key string obtained through the dashboard, encoded with RFC 4648 Base64.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
 --header "Authorization: Basic eFZMeUh3LnI3Q0E5QTp3Ui1PNUhySjVSTG5mT1o1RGYxaXJsak5NeGp5UVZV
OHBnT1pJTFVWWVRZ
"

When using a generic HTTP client library that accepts separate username and password arguments for an HTTP request, the application key can be split at the first colon, with the initial segment being used as the username, and the remaining string (without the leading colon) used as the password.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
 --user "xVLyHw.r7CA9A:wR-O5HrJ5RLnfOZ5Df1irljNMxjyQVU8pgOZILUVYTY"

Token Authentication

Using a token obtained via the REST API requestToken endpoint, tokens provide a means to authenticate with Ably without sharing a private API key. Tokens have a short lifetime and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope – such as a limited set of access rights or capabilities) or being limited to use by a specific clientId identity – and therefore token-based authentication provides the flexibility to implement trusted identities and access control policies in the application. See Authentication for more details.

The requestToken endpoint may be used without explicit authentication, relying on the implicit authentication of submitting a validly signed token request.

Usage in HTTP request header

Authorization: Bearer <Base64-encoded token string>

The <Base64-encoded token string> is the token attribute of the token generated by requestToken, encoded with RFC 4648 Base64. If using a generic HTTP client library it will probably be necessary to add the Authorization header explicitly.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
 --header "Authorization: Bearer eFZMeUh3LkEtcHdoN3cxQXhVZnZKNjhtX1lZZ2cxRUo1VnhGMlMyY3FENUJh
WWlQT3dKX2JLa25B
"

API Reference

View the REST API Reference.


Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.