new Ably.Rest(String keyOrTokenId)
This will instantiate the REST library with the provided API key or Token ID string.
new Ably.Rest(ClientOptions clientOptions)
This will instantiate the library using the specified ClientOptions.
The Rest constructor is used to instantiate the library. The Rest library may be instantiated multiple times with the same or different
ClientOptions in any given context. Except where specified otherwise, instances operate independently of one another.
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.
A private API key string for
ClientOptions#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
key 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.
ClientOptions#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
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 instantiated without a
token, and an initial token will be obtained automatically when required.
Read more on authentication.
The REST client exposes the following public attributes:
A reference to the
Auth authentication object configured for this client library.
The client ID string, if any, configured for this client connection. See authentication for more information on authentication and using a client ID.
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.
- an optional object containing the query parameters
- is a function of the form:
The following options, as defined in the REST
/stats API endpoint, are permitted:
- beginning of time earliest time in milliseconds since the epoch for any stats retrievedType:
- current time latest time in milliseconds since the epoch for any stats retrievedType:
- 100 maximum number of messages to retrieve up to 1,000Type:
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 queryType:
time(callback(ErrorInfo err, Number time))
Obtains the time from the Ably service as milliseconds 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.
- 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 Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about Basic authenticationType:
- An authenticated token. This can either be a
TokenRequestobject, or token string (obtained from the
tokenproperty of a
TokenDetailscomponent of an Ably TokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as
authCallback. Read more about Token authenticationType:
- A function which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed
TokenDetails(in JSON format); an Ably JWT. See an authentication callback example or our authentication documentation for details of the Ably TokenRequest format and associated API calls.Type:
- A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed
TokenDetails(in JSON format); an Ably JWT. For example, this can be used by a client to obtain signed Ably TokenRequests from an application server.Type:
GETThe HTTP verb to use for the request, either
- A set of key value pair headers to be added to any request made to the
authUrl. Useful when an application requires these to be added to validate the request or implement the response. Type:
- A set of key value pair params to be added to any request made to the
authUrl. When the
GET, query params are added to the URL, whereas when
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:
- An authenticated
TokenDetailsobject (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as
authCallback. Use this option if you wish to use Token authentication. Read more about Token authenticationType:
- 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 as it would lead to a possible compromise of the private API key while in transit. Find out more about TLSType:
- A client ID, used for identifying this client when publishing messages or for presence purposes. The
clientIdcan be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a
clientIdmay also be implicit in a token used to instantiate the library; an error will be raised if a
clientIdspecified here conflicts with the
clientIdimplicit in the token. Find out more about client identitiesType:
- false When true, forces Token authentication to be used by the library. Please note that if a
clientIdis not specified in the
TokenParams, then the Ably Token issued will be anonymousType:
- null Enables enterprise customers to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our platform customization guide for more details.Type:
- false When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.Type:
[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the fallback host functionality is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.Type:
- Optional. Can be used to pass in arbitrary connection parameters, such as
- true If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. Find out more about the benefits of binary encodingType:
- false If true, the library will query the Ably servers for the current time when issuing TokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably TokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon . The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.Type:
- When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably
Stats object represents an application’s statistics 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.
- the length of the interval that this statistic covers, such as
- the UTC time at which the time period covered by this
Statsobject starts. For example, an interval ID value of “2018-03-01:10″ in a
daywould indicate that the period covered is “2018-03-01:10 .. 2018-03-01:11″. All
Statsobjects, except those whose
minute, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer the
unitby looking at the resolution of the
Statsobjects covering an individual minute will have an interval ID indicating that time; for example “2018-03-01:10:02″.Type:
- aggregate count of both
- breakdown of API requests received via the Ably REST APIType:
- breakdown of channel related stats such as min, mean and peak channelsType:
- breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connectionsType:
- statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messagesType:
- statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, organized into normal channel messages or presence messagesType:
- messages persisted and later retrieved via the history APIType:
- breakdown of Ably Token requests received via the Ably REST API.Type:
- Detailed stats on push notifications, see our Push documentation for more detailsType: