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:

  • 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.

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 »


API reference
Documentation

Get started now with our free plan

It includes 3m messages per month, 100 peak connections, 100 peak channels, and loads of features.

Create your free account