Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

REST Client Library API

The Ably REST client libraries offer a simple stateless API to interact directly with Ably’s REST API. All official client library APIs are consistent across every language offering message publishing and message history, presence state and historical event retrieval, token generation for clients and authentication, intelligent datacenter routing, symmetric encryption and access to realtime metrics.

The Ably REST client library is available in most popular languages and platforms including including Javascript, iOS, Android, Java, .NET, Node.js, Python, Ruby, PHP, Go and more…

Download one of our REST client libraries now »

Quick intro to the REST library

The REST library communicates with the Ably service using the HTTP protocol for all operations and is effectively stateless. A stateless library is often preferred server-side as it allows communication to consist of independent pairs of request and response without the need to retain session information or any in-flight request state. Whilst Ably’s REST libraries cannot subscribe to data published in real time, they can publish and retrieve realtime data.

Ably organizes realtime data (messages) within applications into named channels that are the “unit” of distribution. Every message published on a channel by a REST or Realtime client is broadcast by Ably to all realtime subscribers on that channel. This scalable and resilient messaging pattern is commonly called pub/sub.

Data published on a channel is packaged as a message by the library before being sent to the Ably service. The message can contain, in addition to a binary, string or JSON payload, an event name and additional metadata in the extras field.

Token authentication is the recommended authentication scheme for client-side devices because tokens are short-lived, their privileges are configured when issued and secret keys are never shared. Typically tokens are issued by your servers to clients that authenticate with your your servers first.

These concepts are illustrated in the diagram below:


REST client diagram

An Ably REST client library is responsible for:

Channel requests
Providing publish and history functionality on channels.
Presence requests
Providing channel presence state and history retrieval on channels.
Data interoperabilty
Ensuring messages and their payloads (JSON, strings or binary data) are encoded and decoded in a uniform way to ensure interoperability between all supported platforms.
Tokens
Issuing either tokens or token requests with appropriate privileges to authenticated or anonymous clients.
Intelligent routing
Ensuring that requests are automatically serviced by an available datacenter.
Encryption
Encrypting payloads with the optional user-generated encryption key ensuring payloads cannot be decrypted whilst in transit or by any party without the private key.

When to use REST vs Realtime libraries

The REST client library is most commonly used server-side i.e. on your application servers, and is stateless. Reasons to use the REST library are:

The Realtime library is most commonly used client-side and is stateful, it establishes a connection to Ably for that client and maintains state for the life of the connection. Reasons to use the Realtime library are:

Other libraries and supported protocols to consider

Diving into the documentation

The Realtime Client Library documentation API is structured as follows:

Step-by-step tutorials

We have a number of tutorials in a wide range of languages to help walk you through some of the key features of our Ably client libraries.
View the Ably tutorials »


Back to top