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 JavaScript, iOS, Android, Java, .NET, Node.js, Python, Ruby, PHP, Go and more…

Download one of our REST client libraries now »

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 servers first.

These concepts are illustrated in the diagram below:

An Ably REST client library is responsible for:

Channel requests

Providing publish and history functionality on channels.

Presence requests

Providing channel presence state and presence 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.

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:

• Your application server is used to primarily issues tokens for clients and/or publish messages on channels.
• Your application is mostly stateless i.e. you process a request or respond to an event, and then move onto the next request or event without any previous state carrying through.
• Your prefer a synchronous request over an asynchronous request. Note not all REST libraries are synchronous, but where the platform offers a synchronous and asynchronous approach, the REST libraries are more often synchronous.

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:

• You are developing a mobile, desktop or web client that needs to subscribe to messages in real time.
• You want to maintain a persistent connection to Ably, attach to one or more channels, and publish and subscribe to messages.
• Your application needs to register its presence on a channel, or listen for others becoming present in real time.

• If you want to consume realtime data from one or more of your servers, then we recommend you consider using our Ably Queues or Firehose. With Integrations, you can consume realtime data in a robust, resilient and scalable way across multiple support protocols. Find our more about the Ably Integrations.
• If you want realtime messages or presence events to trigger execution of code on your servers or in a server-less environment (such as AWS Lambda), then you should consider Webhooks.
• If you want to use another realtime protocol such as MQTT or perhaps even one of our competitors’ protocols, you should review the realtime protocols we support with our Protocol Adapters

The Realtime Client Library documentation API is structured as follows:

• Constructor & usage examples
• Channels
• Messages
• Presence
• Authentication
• History
• Encryption
• Statistics
• Types

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 »