REST SDK: Constructor
Create a client
The Ably REST library constructor is overloaded allowing it to be instantiated using aClientOptions object, or more simply using a string containing an API key or Token.
Ably::PubSub::Server.create_http_client(String key_or_token_id)
This will instantiate the REST library with the provided API key or Token ID string.
Server-package clients should authenticate with an API key; see Server clients and token authentication.
Ably::PubSub::Server.create_http_client(ClientOptions client_options)
Import the factory with require 'ably/pubsub/server'.
The HTTP client may be created multiple times with the same or different ClientOptions in any given context. Except where specified otherwise, instances operate independently of one another.
Authentication
The HTTP client 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#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 Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. 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 Ably TokenRequests and use token authentication when necessary.
Token Authentication
The ClientOptions#token option takes a token string, and assumes that the Ably-compatible 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 :auth_url and :auth_callback options are provided to allow a user of the library to provide new Ably-compatible tokens or Ably TokenRequests to the library as required; using these options allows the library to be instantiated without a key or token, and an initial token will be obtained automatically when required.
Read more on authentication.
Ably::PubSub::Http::Client Attributes
The REST client exposes the following public attributes:
auth
A reference to the Auth authentication object configured for this client library.
push
A reference to thePush object in this client library.
channels
Channels is a reference to the Channel collection instance for this library indexed by the channel name. You can use the Get method of this to get a Channel instance. See channels and messages for more information.
Ably::PubSub::Http::Client Methods
stats
PaginatedResult<Stats> stats(Hash options)
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
| Parameter | Description |
|---|---|
| options | An optional Hash containing the query parameters |
| &block | Yields a PaginatedResult<Stats> object |
options parameters
The following options, as defined in the REST /stats API endpoint, are permitted:
| Parameter | Description | Type | Default |
|---|---|---|---|
| :start | Earliest Time or time in milliseconds since the epoch for any stats retrieved | Int or Time | beginning of time |
| :end | Latest Time or time in milliseconds since the epoch for any stats retrieved | Int or Time | current time |
| :direction | :forwards or :backwards | Symbol | backwards |
| :limit | Maximum number of stats to retrieve up to 1,000 | Integer | 100 |
| :unit | :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 | String | minute |
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
time
Time time
Obtains the time from the Ably service as a Time object. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably TokenRequests with a more accurate timestamp should use the queryTime clientOptions instead of this method).
Returns
On success, the Time is returned.
Failure to retrieve the Ably server time will raise an AblyException.
request
HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)
Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to handle authentication, paging, fallback hosts, MsgPack and JSON support, etc. themselves.
Parameters
| Parameter | Description | Type |
|---|---|---|
| method | either get, post, put, patch or delete | String |
| path | the path to query | String |
| params | (optional) any querystring parameters needed | Object |
| body | (optional; for post, put and patch methods) the body of the request, as anything that can be serialized into JSON, as a JToken. | Serializable |
| headers | (optional) any headers needed. If provided, these will be mixed in with the default library headers | Object |
Returns
On successfully receiving a response from Ably, the returned HttpPaginatedResponse contains a status_code and a success boolean, headers, and an items array containing the current page of results. It supports pagination using next and first methods, identically to PaginatedResult.
Failure to obtain a response will raise an AblyException. (Note that if a response is obtained, any response, even with a non-2xx status code, will result in an HTTP Paginated Response, not an exception).
Related types
ClientOptions
ClientOptions is a Hash object and is used in the Ably::PubSub::Server.create_http_client factory's options argument. The following key symbol values can be added to the Hash:
Attributes
| Parameter | Description | Type |
|---|---|---|
| :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 Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about Basic authentication | String |
| :token | An authenticated token. This can either be a TokenDetails object, a TokenRequest object, or token string (obtained from the token property of a TokenDetails component 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 :auth_url or :auth_callback. Read more about Token authentication | String, TokenDetails or TokenRequest |
| :auth_callback | A proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) 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 TokenRequest; a TokenDetails (in JSON format); an Ably JWT. See our authentication documentation for details of the Ably TokenRequest format and associated API calls. | Proc |
| :auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed TokenRequest; a 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. | String |
| :auth_method | The HTTP verb to use for the request, either :get or :postdefault: :get | Symbol |
| :auth_headers | 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. | Hash |
| :auth_params | A set of key value pair params to be added to any request made to the authUrl. When the authMethod is GET, query params are added to the URL, whereas when authMethod 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. | Hash |
| :token_details | An authenticated TokenDetails object (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 :auth_url or :auth_callback. Use this option if you wish to use Token authentication. Read more about Token authentication | TokenDetails |
| :tls | 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 TLS default: true | Boolean |
| :client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The client_id can 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 client_id may also be implicit in a token used to instantiate the library; an error will be raised if a client_id specified here conflicts with the client_id implicit in the token. Find out more about client identities | String |
| :use_token_auth | When true, forces Token authentication to be used by the library. Please note that if a client_id is not specified in the ClientOptions or TokenParams, then the Ably Token issued will be anonymous.default: false | Boolean |
| :endpoint | The endpoint that both REST requests and the realtime connection use. It can be a routing policy name such as acme (resolved to acme.realtime.ably.net), a non-production routing policy name prefixed with nonprod: such as nonprod:sandbox (resolved to sandbox.realtime.ably-nonprod.net), or a hostname such as localhost, which is used as given and has no default fallback hosts. Enables enterprise customers to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our platform customization guide for more details.default: nil, which resolves to main.realtime.ably.net | String |
| :idempotent_rest_publishing | 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. Enabled by default in all current Ably SDKs. default: true | Boolean |
| :fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When set, these replace the default fallback hosts, which are derived from :endpoint, and an empty array disables the fallback host functionality. When :endpoint is a hostname there are no default fallback hosts. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.default: [main.a.fallback.ably-realtime.com, main.b.fallback.ably-realtime.com, main.c.fallback.ably-realtime.com, main.d.fallback.ably-realtime.com, main.e.fallback.ably-realtime.com] | String [] |
| :transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as heartbeatInterval and remainPresentFor | Hash |
| :log_level | 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. The default is :error. | Symbol, Logger::SEVERITY |
| :logger | A Ruby Logger compatible object to handle each line of log output. If logger is not specified, STDOUT is used. | STDOUT Logger |
| :use_binary_protocol | If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the benefits of binary encoding default: true | Boolean |
| :query_time | 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.default: false | Boolean |
| :default_token_params | When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | TokenParams |
Ably::Models::Stats
A 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.
Attributes
| Property | Description | Type |
|---|---|---|
| unit | The length of the interval that this statistic covers, such as minute, hour, day or month | String |
| interval_id | The UTC time at which the time period covered by this Stats object starts, at the resolution of unit: for example 2018-03-01:10:02 (minute), 2018-03-01:10 (hour), 2018-03-01 (day) or 2018-03 (month) | String |
| interval_time | A Time object representing the parsed interval_id (the UTC time at which the time period covered by this Stats object starts) | Time |
| entries | The statistics for the interval, as a flat Hash keyed by dot-separated metric name, such as messages.all.all.count. The set of metrics available is described by the JSON schema referenced by schema | Hash |
| in_progress | If present, the last sub-interval, within the interval, for which statistics are included. Only present for an interval that is still in progress | String |
| app_id | The ID of the Ably application the statistics relate to | String |
| schema | The URL of the JSON schema that describes the structure of entries | String |
HttpPaginatedResponse
AnHttpPaginatedResponse is a superset of PaginatedResult, which is a type that represents a page of results plus metadata indicating the relative queries available to it. HttpPaginatedResponse additionally carries information about the response to an HTTP request. It is used when making custom HTTP requests.
Attributes
| Property | Description | Type |
|---|---|---|
| status_code | The HTTP status code of the response | Number |
| success | Whether the HTTP status code indicates success. This is equivalent to 200 <= status_code < 300 | Boolean |
| headers | The headers of the response | Object |
| error_code | The error code if the X-Ably-Errorcode HTTP header is sent in the response | Int |
| error_message | The error message if the X-Ably-Errormessage HTTP header is sent in the response | String |
Methods
first
HttpPaginatedResponse first
Returns a new HttpPaginatedResponse for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields an HttpPaginatedResponse.
has_next?
Boolean has_next?
Returns true if there are more pages available by calling next and returns false if this page is the last page available.
last?
Boolean last?
Returns true if this page is the last page and returns false if there are more pages available by calling next available.
next
HttpPaginatedResponse next
Returns a new HttpPaginatedResponse loaded with the next page of results. If there are no further pages, then null is returned. When using the Realtime library, the first method returns a Deferrable and yields an HttpPaginatedResponse.
Example
TheHttpPaginatedResponse interface is a superset of PaginatedResult, see the PaginatedResult example