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

Client Library Development Guide

Ably has invested in the development of comprehensive and consistent client libraries for all widely used platforms and languages. Comprehensive, in that all client libraries are feature complete, consistent, in that, where possible, the exposed API is the same in all languages and platforms.

The reference material in this section is intended to support developers in creating and extending new libraries.

See the Ably client libraries available »

Overview

Ably client libraries provide REST and/or Realtime functionality.

REST library functionality

REST libraries provide a convenient way to access the Ably REST API, and are intended to be used by clients that do not need realtime updates from the Ably service, but will instead send requests to Ably to:

The REST API has a stable interface definition at the REST level – i.e. the routes, formats and error codes are in principle accessible via any REST library. The Ably REST libraries provide convenience functionality and data center awareness however they are not the exclusive means to interface with the Ably REST interface.

See the complete REST library specification

Realtime library functionality

Realtime libraries provide access to the messaging service, enabling realtime message publication, channel subscription and presence. The Realtime library typically extends the REST library, so that Realtime clients can access the REST functionality as well.

While REST is supportable in any environment supporting HTTP, the Realtime API is supportable only in environments that support asynchronous or evented IO. The environments we target for the Realtime library support are those that might realistically be used to implement realtime system backends such as Node.js, Java or Go, and environments that might be used to develop client apps such as a browser Javascript environment, iOS or Android.

The Realtime interface is implemented using an Ably-defined protocol (over WebSockets and other transports) and, although that protocol is published, we reserve the right to change the protocol and drop support for superseded protocol versions at any time. Of course, we don’t want to make life difficult for client library developers, so any incompatible changes will be very carefully considered, but nonetheless developers must regard the protocol definition as being subject to change. Application developers using the Ably Realtime API should use one of the Ably client libraries and can expect that API to be stable and supported even if the protocol changes underneath.

See the complete Realtime and REST client library specification

Developing an Ably client library

If you are interested in developing or forking one of our client libraries, please do get in touch as we’d love to help. Equally, if you feel we’re missing a client library for your platform or language, please do contact us.

The following resources are useful references when developing client libraries for Ably:

Client library features and prioritisation

Whilst all officially supported Ably client libraries support all features defined in the test specification, we recommend an approach that focuses on the most commonly used features first.

First, read the Ably client library feature overview that will provide you with a good high level view of all functionality and features available in the client libraries. Afterwards, we advise that you read the recommended client library development feature prioritisation document as it will help you, as a client library developer, to understand which features are most important and logical to start with.

Sandbox environment for client library testing

All of the Ably client libraries have test suites that run the test suite against temporary apps that are created during the test setup. Although Ably does not provide a public provisioning API for account management (in the production system this is available only through the website registration and dashboard) there is a limited API provided via the REST
interface in the sandbox environment to enable test applications and keys to be provisioned automatically for each test run. Therefore, all tests are set up to run against the sandbox environment.

See Test API for details about the test routes provided in the REST API.

Realtime protocol definition

See the current version of the Ably realtime protocol definition. Please note that this protocol is subject to change, we recommend you use one of the Ably client libraries if you want any API compatibility guarantees.

REST API definition

See the Ably REST API definition which can be considered stable and not subject to change without the introduction of a versioning system.

Encryption

Ably client libraries support encryption of message content, making it easier to build apps that encrypt content fully end-to-end. See the encryption specification.

Realtime transports

All Ably client libraries at a minimum support WebSockets as our primary transport. Additionally, libraries may support one or more additional fallback transports such as Comet, XHR streaming, JSONP etc. The following transports are currently documented:

Documentation

All client libraries share API documentation within this repository so that where possible, the documentation is DRY. Where client libraries differ in regards to their API or usage, the language specific variations are documented in this repository, which in turn are replicated in the primary Ably documentation.

All client libraries developed or modified must reflect the changes to this documentation. You can fork this repository at https://github.com/ably/docs and issue a Pull Request.

Read how to use our Ably Textile format.


Back to top