Warning: You are viewing an old version (1.0) of this documentation. We recommend you view the latest version 1.2.
REST Client Library API

Using the REST library

The Ably REST client libraries offer a simple stateless API to interact directly with Ably’s REST API. The REST library is typically used server-side to issue tokens, publish messages, and retrieve message history. If you are building a client-side application, you want to consider using our stateful Ably Realtime client libraries.

The Ably REST client library is available for most popular languages and platforms with a consistent API across all platforms. You can view this documentation with your preferred language API and code examples using the language selector navigation above. If your preferred language is not listed in the language selector, we recommend you download a library in your preferred language and use this documentation as an API reference.

The REST library for browser JavaScript environments should be loaded from the Ably CDN as follows:

<script lang="text/javascript" src="//cdn.ably.io/lib/ably.min-1.js"></script>

You can also obtain the library as an NPM module, or download the source directly from Github

The script and module both contain the Realtime and REST libraries as well as all their dependencies. To instantiate the REST library:

var rest = new Ably.Rest({ key: apiKey });

When including the client library from our CDN, we recommend you lock into major version 1 of the library. According to the semantic versioning scheme we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version 1 of the library by including https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e 1.*.*). If you want to lock into minor version 1.0 and receive all patch fixes automatically (i.e. 1.0.*), then use https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the .min suffix can be dropped if you want the non-minified version for debugging.

View a complete list of the JavaScript library releases

The REST library for Node.js is suitable for clients and servers and is hosted on Github and is obtainable as an NPM module directly from npm. Install with:

npm install ably

The Ably Node.js module contains both the REST and Realtime libraries; each is exported separately by the module. To instantiate the REST library:

var Ably = require('ably');
var rest = new Ably.Rest({ key: apiKey });

The REST library for Ruby is hosted on Github and is published as a RubyGem and can be installed as follows:

gem install ably-rest

If using bundler, simply add the following to your Gemfile and run bundle install:

gem 'ably-rest'

The Ably Ruby REST gem contains only the REST API and limited dependencies. To instantiate the REST library:

ably = Ably::Rest.new(key: api_key)

The REST library for Python is hosted on Github and is published on PyPI and can be installed as follows:

pip install ably

Then it can be imported and instantiated as follows:

from ably import AblyRest
client = AblyRest(api_key)

Note on string encodings

Since Ably supports both string and binary payloads, to avoid ambiguity, we recommend that strings passed to the library for publishing to Ably (eg as an event name or payload data) should be unicode strings. In Python 3 this is the normal string type, but in Python 2 it is not, so we suggest you prefix string literals with u prefix (eg u'eventname' – or alternatively, use from __future__ import unicode_literals, which will make this automatic), and to explicitly decode any user input (eg raw_input().decode(sys.stdin.encoding).

The REST library for PHP is hosted on Github and is available as a composer package on packagist which can be installed as follows:

composer require ably/ably-php --update-no-dev

Then simply require composer’s autoloader:

require_once __DIR__ . '/../vendor/autoload.php';

To instantiate the REST library:

$ably = new Ably\AblyRest(apiKey);

The REST library for Java and Android is hosted on Github and can be used by adding one line to build.gradle dependencies section.

For Java applications:

compile 'io.ably:ably-java:1.0.0'

For Android apps:

compile 'io.ably:ably-android:1.0.0'

In the above example a specific version of the library is referenced, however we recommend you check which is the latest stable version and always use that.

Ensure the library is included in your classpath as follows:

import io.ably.lib.types.*;
import io.ably.lib.rest.*;
ClientOptions options = new ClientOptions(apiKey);
AblyRest rest = new AblyRest(options);

The REST library for .NET is available as a Nuget Package. Open the nuget console in visual studio and type.

PM> Install-Package ably.io

Alternatively, search for the ‘ably.io’ package through the Nuget UI

using IO.Ably;

ClientOptions clientOptions = new ClientOptions("<API Key>");
AblyRest rest = new AblyRest(clientOptions);

The Ably library is hosted on Github and is available as a CocoaPod. Add this line to your application’s Podfile:

pod 'Ably'

And install with pod install. Then in your files:

#import "Ably/Ably.h"

ARTRest rest = [[ARTRest alloc] initWithKey:apiKey];
import Ably

let rest = ARTRest(key: apiKey)

The supported client options are described below.


If you would like to see examples of using the Ably REST client library, then we recommend you take a look at our
REST tutorials.

API Reference

View the Constructor 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.