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

Using the REST library

The Ably REST client libraries offer a convenient and simple API to interact directly with the Ably REST API providing publish and historical message retrieval, basic and token authentication, automatic handling of changing network conditions, optional symmetric encryption and access to channel, presence and metrics history.

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, please download the library in your preferred language and use that as a 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-0.js" />

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 instance 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 0 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 0 of the library by including https://cdn.ably.io/lib/ably.min-0.js, you will receive all minor updates and patch fixes automatically (i.e 0.*.*). If you want to lock into minor version 0.8 and receive all patch fixes automatically (i.e. 0.8.*), then use https://cdn.ably.io/lib/ably.min-0.8.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 instance 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 library and its dependencies. However, Ably Ruby gem contains both the REST and Realtime libraries including the EventMachine depdendency. To instance 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 instance the REST library:

$ably = new Ably\AblyRest(apiKey);

The REST library for Java and Android is hosted on Github and is downloadable as a JAR from https://github.com/ably/ably-java/releases or via JCentre.

Ensure the JAR 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 'AblyRealtime'

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.

REST API ReferenceREST::Client API reference

Constructor

The Ably REST library constructor is overloaded allowing it to be instanced using a ClientOptions object, or more simply using a string containing an API key or Token.

new Ably.Rest(String keyOrTokenId)Ably::Rest.new(String key_or_token_id)new Ably\AblyRest(String key_or_token_id)new io.ably.lib.AblyRest(String keyOrTokenIdString)new IO.Ably.AblyRest(string key);- (instancetype)initWithKey:(NSString *)keyinit(key: String)
init(token: String)
AblyRest(String api_key)

This will instance the REST library with the provided API key or Token ID string.

new Ably.Rest(ClientOptions clientOptions)Ably::Rest.new(ClientOptions client_options)new Ably\AblyRest(ClientOptions client_options)new io.ably.lib.AblyRest(ClientOptions clientOptions)new IO.Ably.AblyRest(ClientOptions clientOptions)- (instancetype)initWithOptions:(ARTClientOptions *)options;init(options: ARTClientOptions)AblyRest(ClientOptions client_options)

This will instance the library using the specified ClientOptions.

This will instance the library and create a new Ably::Rest::Client using the specified ClientOptions.

The Rest constructor is used to instance the library. The Rest library may be instanced multiple times with the same or different ClientOptions in any given context. Except where specified otherwise, instances operate independently of one another.

Authentication

The REST library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on authentication.

Basic Authentication

A private API key string for ClientOptions#keyClientOptions#Key or the constructor, as obtained from the application dashboard, is required for Basic Authentication. Use this option if you wish to use Basic authentication, or if you want to be able to request tokens without needing to defer to a separate entity to sign token requests. Note that initializing the library with a keyKey does not necessarily mean that the library will use Basic auth; using the private key it is also able to create and sign token requests and use token authentication when necessary.

Token Authentication

The ClientOptions#tokenClientOptions#Token option takes a token string, and assumes the token has been obtained from some other instance that requested the token. Use the token option if you are provided with a token to use and you do not have a key (or do not have a key with the capabilities that you require).

Since tokens are short-lived, it is rarely sufficient to start with a token without the means for refreshing it. The authUrl and authCallback:auth_url and :auth_callbackauth_url and auth_callbackAuthUrl and AuthCallback options are provided to allow a user of the library to provide new tokens or token requests to the library as required; using these options allows the library to be instanced without a key or tokenKey or Token, and an initial token will be obtained automatically when required.

Read more on authentication.

AblyRest Propertiesio.ably.lib.AblyRest MembersAbly::Rest::Client AttributesARTRest Properties

The REST client exposes the following public attributesmembersproperties:

authAuth

A reference to the Auth authentication object configured for this client library.

channelsChannels

A reference to the Channel collection instance for this library indexed by the channel name. See channels and messages for more information.

clientIdclient_idClientId

The client ID string, if any, configured for this client connection. See authentication for more information on authentication and using a client ID.

AblyRest Methodsio.ably.lib.AblyRest MethodsAbly::Rest::Client MethodsARTRealtime Methods

statsStats

stats(Object options, callback(ErrorInfo err, PaginatedResult<Stats> results))PaginatedResult<Stats> stats(Hash options)PaginatedResult<Stats> stats(kwargs_options)PaginatedResult<Stats> stats(Array options)PaginatedResult<Stats> stats(Param[] options)Task<PaginatedResult<Stats>> StatsAsync(StatsRequestParams query)stats(query: ARTStatsQuery?, callback: (ARTPaginatedResult#/realtime/types#paginated-result<ARTStats>?, ARTErrorInfo?) → Void) throws

This call queries the REST /stats API and retrieves your application’s usage statistics. A PaginatedResult is returned, containing an array of Stats for the first page of results. PaginatedResult objects are iterable providing a means to page through historical statistics. See an example set of raw stats returned via the REST API.

See statistics for more information.

Parameters

optionsquery
an optional objectHashARTStatsQueryStatsRequestParamsParam[] array containing the query parameters
callback
is a function of the form: function(err, result)
&block
yields a PaginatedResult<Stats> object
callback
called with a ARTPaginatedResult<ARTStats> object or an error

options parametersARTStatsQuery propertiesStatsRequestParams properties

The following options, as defined in the REST /stats API endpoint, are permitted:

start:startStart
beginning of time earliest DateTimeOffset or Time or time in milliseconds since the epoch for any stats retrieved
Type: LongInt or @TimeDateTimeOffset
end:endEnd
current time latest DateTimeOffset or Time or time in milliseconds since the epoch for any stats retrieved
Type: LongInt or @TimeDateTimeOffset
direction:directionDirection
backwards :forwards or :backwards
Type: StringSymbolDirection enum
limit:limitLimit
100 maximum number of messages to retrieve up to 1,000
Type: Integer
unit:unitUnit
minute :minute, :hour, :day or :month. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
Type: StringARTStatsGranularitySymbolStatsIntervalGranularity enum

Callback result

On success, result contains a PaginatedResult encapsulating an array of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

On failure to retrieve stats, err contains an ErrorInfo object with an error response as defined in the Ably REST API documentation.

Returns

On success, the returned PaginatedResult encapsulates an array of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

Failure to retrieve the stats will raise an AblyException

Returns

The method is asynchronous and return Task which needs to be awaited.

On success, the returned PaginatedResult encapsulates a list of Stats objects corresponding to the current page of results. PaginatedResult supports pagination using NextAsync and FirstAsync methods.

Failure to retrieve the stats will raise an AblyException

timeTime

time(callback(ErrorInfo err, Number time))Time timeInt time()Integer time()long time()Task TimeAsync()time(callback: (NSDate?, NSError?) → Void)

Obtains the time from the Ably service as a Time objecta DateTimeOffset objectmilliseconds since epoch. This may be required on clients that do not have access to a sufficiently well maintained time source and wish to issue token requests with a more accurate timestamp.

Callback result

On success, time is a number containing the number of milliseconds since the epoch.

On failure to retrieve the Ably server time, err contains an ErrorInfo object with an error response as defined in the Ably REST API documentation.

Returns

On success, milliseconds since epochthe Timethe DateTimeOffset is returned.

Failure to retrieve the Ably server time will raise an AblyException.

ClientOptionsARTClientOptionsio.ably.lib.types.ClientOptionsIO.Ably.ClientOptions

ClientOptions is a plain Javascript object and is used in the Ably.Rest constructor’s options argument. The following attributes can be defined on the object:

ClientOptions is a Hash object and is used in the Ably::Rest constructor’s options argument. The following key symbol values can be added to the Hash:

ClientOptions is a associative array and is used in the Ably\AblyRest constructor’s options argument. The following named keys and values can be added to the associative array:

ARTClientOptions is used in the AblyRest constructor’s options argument.

ClientOptions is a plain Javascript object and is used in the Ably.Realtime constructor’s options argument. The following attributes can be defined on the object:

ClientOptions is a Hash object and is used in the Ably::Realtime constructor’s options argument. The following key symbol values can be added to the Hash:

ClientOptions is a associative array and is used in the Ably\AblyRest constructor’s options argument. The following named keys and values can be added to the associative array:

ARTClientOptions is used in the AblyRealtime constructor’s options argument.

PropertiesMembersAttributesKeyword arguments

keyKey:key
The full key string, as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue tokens without needing to defer to a separate entity to sign token requests. Read more about Basic authentication
Type: String
tokenToken:token
An authenticated token string that is most commonly obtained from the @token@>Token property of a TokenDetails component of a token request response. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: String
tokenDetailsTokenDetailstoken_details:token_details
An authenticated TokenDetails object that is most commonly obtained from of a token request response. Use this option if you wish to use Token authentication. Read more about Token authentication
Type: TokenDetails
tlsTls:tls
true A boolean value, indicating whether or not a TLS (“SSL”) secure connection should be used. An insecure connection cannot be used with Basic authentication ensuring private keys are compromised in transit. Find out more about TLS
Type: Boolean
clientIdClientIdclient_id:client_id
A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instanced with a key; note that a clientIdclient_idClientId may also be implicit in a token used to instance the library; an error will be raised if a clientIdclient_id specified here conflicts with the clientIdclient_idClientId implicit in the token. Find out more about client identities
Type: String
authCallbackAuthCallbackauth_callback:auth_callback
A functionfunction with the form function(tokenParams, callback(err, tokenOrTokenRequest))TokenCallback instancecallable (eg a lambda)proc / lambda which is called when a new token is required. The role of the callback is to either generate a signed TokenRequest which may then be submitted automatically by the library to the Ably REST API requestToken; or to provide a valid token in as a TokenDetails object. See an authentication callback example or our authentication documentation for details of the token request format and associated API calls.
Type: CallableTokenCallbackProcFunc<TokenParams, Task<TokenDetails>>
authUrlAuthUrlauth_url:auth_url
A URL that the library may use to obtain a token string (in plain text format), or a signed TokenRequest or TokenDetails (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server.
Type: StringUri
authMethodAuthMethodauth_method:auth_method
GET:get The HTTP verb to use for the request, either GET:get or POST:post
Type: StringSymbolHttpMethod
authHeadersAuthHeadersauth_headers:auth_headers
A set of key value pair headers to be added to any request made to the authUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>
authParamsAuthParamsauth_params:auth_params
A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is GET, query params are added to the URL, whereas when authMethodAuthMethod is POST, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type: ObjectDictHashAssociative ArrayParam []Dictionary<string, string>
useTokenAuthUseTokenAuthuse_token_auth:use_token_auth
false When true, forces Token authentication to be used by the library. Please note that if a client_idclientId is not specified in the ClientOptions or TokenParams, then the token issued will be anonymous.
Type: Boolean
log
Parameters to control the log output of the library. The supplied value must be an object that may contain one or both of the following entries:

  • level: a number controlling the verbosity of the output. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output).

  • handler: a function to handle each line of log output. If handler is not specified, console.log is used.


Note that the log level and log handler have global scope in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type: Object
transports
An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: web_socket, xhr, jsonp.The transports available in the Node.js client library are: web_socket, xhr, comet.
Type: String []
logLevel
5 A number controlling the verbosity of the output from 2 (maximum, verbose) to 6 (errors only). A special value of 99 will silence all logging. Note that the logLevel is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type: Integer
logHandler
System.out PrintStream A LogHandler interface can be specified to handle each line of log output. If logHandler is not specified, System.out is used. Note that the logHandler is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type: PrintStream

To set the log level and custom logger sink when using the .Net library, configure the static IO.Ably.Logger class or specify the ClientOptions:

LogLevel
Error This is an enum controlling the verbosity of the output from Debug (maximum) to Error (errors only). A special value of None will silence all logging. Note that the LogLevel is a static variable in the library and will thus not act independently between library instances.
Type: Enum
LoggerSink
IO.Ably.DefaultLoggerSink The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure.
logLevel
ARTLogLevelWarn An enum controlling the verbosity of the output from ARTLogLevelVerbose to ARTLogLevelNone. A special value of 99 will silence all logging.
Type: ARTLogLevel
logHandler
A ARTLog object can be specified to handle each line of log output. If logHandler is not specified, a default ARTLog instance is used.
Type: ARTLog *
:log_level
:error Log level for the standard Logger that outputs to STDOUT. Can be set to :fatal, :error, :warn, :info, :debug or :none. Alternatively a Logger severity constant can be specified.
Type: Symbol, Logger::SEVERITY
:logger
STDOUT Logger A Ruby Logger compatible object to handle each line of log output. If logger is not specified, STDOUT is used.
Type: Ruby @Logger
logLevel
Log::WARNING A number controlling the verbosity of the output from 1 (minimum, errors only) to 4 (most verbose);
Type: Integer
logHandler
console.log A function to handle each line of log output. If handler is not specified, console.log is used. Note that the log level and log handler have global scope in the library and will therefore not act independently between library instances when multiple library instances exist concurrently.
Type: Function
useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol
true If set to false, will forcibly disable the binary protocol. The binary protocol is used by default unless it isNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the benefits of binary encoding
Type: Boolean
queryTimequery_time:query_timeQueryTime
false If true, the library will query the Ably servers for the current time instead of relying on a locally-available time of day
Type: Boolean
defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams
When a TokenParams object is provided, it will override the client library defaults when issuing new tokens or token requests
Type: TokenParams

Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsAbly\Models\StatsIO.Ably.Stats

A Stats object represents a application statistic for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our statistics API as well as your application dashboard.

Please note that most attributes of the Stats type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the Ruby library stats documentation which contains exhaustive stats documentation. Ruby and Python however uses under_score case instead of the default camelCase in most languages, so please bear that in mind.

PropertiesMembersAttributesKeyword arguments

allAll
aggregate count of both inbound and outbound message stats
Type: MessageTypes
apiRequestsapi_requestsApiRequests
breakdown of API requests received via the Ably REST API
Type: RequestCount
channelsChannels
breakdown of channel related stats such as min, mean and peak channels
Type: ResourceCount
connectionsConnections
breakdown of connection related stats such as min, mean and peak channels for TLS and non-TLS connections
Type: ConnectionTypes
inboundInbound
statistics such as count and data for all inbound messages received over REST and Realtime connection, broken down by normal channel messages or presence messages
Type: MessageTraffic
interval_granularityIntervalGranularity
A GRANULARITY constantvalueEnum representing the granularity (interval) of this statistic such as :minute, :hour, :day, :month'minute', 'hour', 'day', 'month'Minute, Hour, Day, Month.
Type: Stats::GRANULARITYStringStatsIntervalGranularity enum
intervalIdinterval_idIntervalId
the interval ID provides both the time from which the interval starts as well as the length of time that this statistic covers i.e. the period of time which the stats are aggregated for. For example, an interval ID value of “2016-03-01:10:02” represents a single minute interval for the UTC time presented in the string. However, an interval ID of “2016-03” represents a month interval for the entire month of March 2016 based on UTC time.
Type: String
interval_timeIntervalTime
A TimeDateTimeDateTimeOffset object representing the start of the interval
Type: TimeDateTimeDateTimeOffset
outboundOutbound
statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with WebHooks, broken down by normal channel messages or presence messages
Type: MessageTraffic
persistedPersisted
messages persisted and later retrieved via the history API
Type: MessageTypes
tokenRequeststoken_requestsTokenRequests
breakdown of Token requests received via the Ably REST API.
Type: RequestCount

ARTStatsGranularityStatsGranularity

ARTStatsGranularity is an enum specifying the granularity of a ARTStats interval.

typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
    ARTStatsGranularityMinute,
    ARTStatsGranularityHour,
    ARTStatsGranularityDay,
    ARTStatsGranularityMonth
};
enum ARTStatsGranularity : UInt {
    case Minute
    case Hour
    case Day
    case Month
}

StatsIntervalGranularity is an enum specifying the granularity of a Stats interval.

public enum StatsGranularity
{
    Minute,
    Hour,
    Day,
    Month
}

io.ably.lib.types.Param

Param is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see Channel#history for an example.

Please note that key and value attributes are always strings. If an Integer or other value type is expected, then you must coerce that type into a String.

Members

key
The key value
Type: String
value
The value associated with the key
Type: String

Back to top