From feda7ee3498f56b87a3dbf37b3ca913e4d36a0f3 Mon Sep 17 00:00:00 2001 From: Greg Holmes Date: Thu, 30 Oct 2025 10:37:38 +0000 Subject: [PATCH] Migrate REST SDK API spec Constructor page to MDX --- content/api/rest-sdk.textile | 310 ------- src/pages/docs/api/rest-sdk.mdx | 1454 +++++++++++++++++++++++++++++++ 2 files changed, 1454 insertions(+), 310 deletions(-) delete mode 100644 content/api/rest-sdk.textile create mode 100644 src/pages/docs/api/rest-sdk.mdx diff --git a/content/api/rest-sdk.textile b/content/api/rest-sdk.textile deleted file mode 100644 index d0c0a74911..0000000000 --- a/content/api/rest-sdk.textile +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: Constructor -meta_description: "Client Library SDK REST API Reference constructor documentation." -meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, constructor" -section: api -languages: - - javascript - - nodejs - - php - - python - - ruby - - java - - swift - - objc - - csharp - - go - - flutter -redirect_from: - - /docs/api/versions/v1.1/rest-sdk - - /docs/api/versions/v1.0/rest-sdk - - /docs/api/versions/v0.8/rest-sdk ---- - -h2(#constructor). Constructor - -The Ably REST library constructor is overloaded allowing it to be instantiated using a "@ClientOptions@":#client-options object, or more simply using a string containing an "API key":/docs/auth/basic or "Token":/docs/auth/token. - -bq(definition). - default: new Ably.Rest(String keyOrTokenId) - ruby: Ably::Rest.new(String key_or_token_id) - php: new Ably\AblyRest(String key_or_token_id) - java: new io.ably.lib.AblyRest(String keyOrTokenIdString) - csharp: new IO.Ably.AblyRest(string key); - objc: - (instancetype)initWithKey:(NSString *)key
(instancetype)initWithToken:(NSString *)token - swift: init(key: String)
init(token: String) - python: AblyRest(String api_key) - flutter: ably.Rest(key: keyOrTokenIdString) - go: ably.NewREST(ably.WithKey(key string)) (*RestClient, error) - -This will instantiate the REST library with the provided API key or Token ID string. - -bq(definition). - default: new Ably.Rest("ClientOptions":#client-options clientOptions) - ruby: Ably::Rest.new("ClientOptions":#client-options client_options) - php: new Ably\AblyRest("ClientOptions":#client-options client_options) - java: new io.ably.lib.AblyRest("ClientOptions":#client-options clientOptions) - csharp: new IO.Ably.AblyRest("ClientOptions":#client-options clientOptions) - objc: - (instancetype)initWithOptions:("ARTClientOptions":#client-options *)options; - swift: init(options: "ARTClientOptions":#client-options) - python: AblyRest("ClientOptions":#client-options client_options) - flutter: ably.Rest(options: "ClientOptions":#client-options clientOptions) - go: ably.NewREST(ably.WithKey(key string), ably.WithClientID(clientID string)) (*RestClient, error) - -blang[default]. - This will instantiate the library using the specified "ClientOptions":#client-options. - -blang[ruby]. - This will instantiate the library and create a new @Ably::Rest::Client@ using the specified "@ClientOptions@":#client-options. - -The REST constructor is used to instantiate the library. The REST library may be instantiated multiple times with the same or different "@ClientOptions@":#client-options in any given context. Except where specified otherwise, instances operate independently of one another. - -h3(#authentication). 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":/docs/auth. - -h4. Basic Authentication - -A private API key string for "@ClientOptions#key@@ClientOptions#Key@":#client-options or the constructor, as obtained from the "application dashboard":https://ably.com/dashboard, is required for "Basic Authentication":/docs/auth/basic. Use this option if you wish to use "Basic authentication":/docs/auth/basic, or if you want to be able to "request Ably Tokens":/docs/auth/token without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a @key@@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. - -h4. Token Authentication - -The "@ClientOptions#token@@ClientOptions#Token@":#client-options 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 "@authUrl@ and @authCallback@@:auth_url@ and @:auth_callback@@auth_url@ and @auth_callback@@AuthUrl@ and @AuthCallback@ options":#client-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@@Key@ or @Token@, and an initial token will be obtained automatically when required. - -Read more on "authentication":/docs/auth. - -blang[objc,swift]. - h3(#thread-safety). Thread safety - - The Cocoa SDK makes the following thread safety guarantees: - - * All public methods and properties can be safely accessed from any thread, both for reading and writing operations. - * Objects like @ARTTokenDetails@ and message data returned by the SDK can be safely read from multiple threads. However, you should not modify these objects after they're created. - * Objects you pass to the library must not be mutated afterwards. Once passed to the SDK, treat them as immutable. You can safely read from them or pass them again, and the library will never modify them. - - All internal operations are dispatched to a single serial GCD queue to ensure thread safety within the SDK. You can specify a custom queue for this using @ARTClientOptions.internalDispatchQueue@, but it must be serial to maintain thread safety guarantees. - - All callbacks provided by you are dispatched to the main queue by default, allowing you to update UI directly without additional thread switching. You can specify a different queue using @ARTClientOptions.dispatchQueue@. The callback queue must be different from @ARTClientOptions.internalDispatchQueue@ to prevent deadlocks. Using the same queue creates circular dependencies where internal operations wait for callbacks, while callbacks wait for the internal queue. - -h2(#properties). - default: AblyRest Properties - jsall: Ably.Rest Properties - java: io.ably.lib.AblyRest Members - ruby: Ably::Rest::Client Attributes - objc,swift: ARTRest Properties - flutter: ably.Rest Properties - -The REST client exposes the following public attributesmembersproperties: - -h6(#auth). - default: auth - csharp,go: Auth - -A reference to the "@Auth@":/docs/api/rest-sdk/authentication authentication object configured for this client library. - -h6(#push). - default: push - -A reference to the "@Push@@ARTPush@":/docs/push object in this client library. - -
- -h6(#device). - default: device - -A reference to the "@LocalDevice@@ARTLocalDevice@":/docs/push/configure/device object. -
- -h6(#channels). - default: channels - csharp,go: Channels - -"@Channels@":/docs/channels is a reference to the "@Channel@":/docs/channels collection instance for this library indexed by the channel name. You can use the "@Get@":/docs/api/rest-sdk/channels#get method of this to get a @Channel@ instance. See "channels":/docs/channels and "messages":/docs/channels/messages/ for more information. - -h2(#methods). - default: AblyRest Methods - jsall: Ably.Rest Methods - java: io.ably.lib.AblyRest Methods - ruby: Ably::Rest::Client Methods - objc,swift: ARTRealtime Methods - flutter: ably.Rest Methods - -h6(#stats). - default: stats - csharp,go: Stats - -bq(definition). - default: stats(Object options, callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> results)) - jsall: stats(Object params?): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":docs/api/rest-sdk/types#stats-type>> - ruby: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(Hash options) - python: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(kwargs_options) - php: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats(Array options) - java: "PaginatedResult":/docs/api/rest-sdk/types#paginated-result<"Stats":#stats-type> stats("Param":#param[] options) - csharp: Task<"PaginatedResult":#paginated-result<"Stats":#stats-type>> StatsAsync("StatsRequestParams":/docs/api/rest-sdk/types#data-request query) - swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":#stats-type>?, ARTErrorInfo?) -> Void) throws - go: (c *RestClient) Stats(params *PaginateParams) (*PaginatedResult, error) - -This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/rest-sdk/types#paginated-result is returned, containing an array of "Stats":#stats-type for the first page of results. "PaginatedResult":/docs/api/rest-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics. - -See "statistics":/docs/metadata-stats/stats for more information. - -<%= partial partial_version('rest/_stats') %> - -h6(#time). - default: time - csharp: Time - -bq(definition). - default: time(callback("ErrorInfo":/docs/api/rest-sdk/types#error-info err, Number time)) - jsall: time(): Promise - ruby: Time time - python: Int time() - php: Integer time() - java: long time() - csharp: Task TimeAsync() - objc,swift: time(callback: (NSDate?, NSError?) -> Void) - go: (c *RestClient) Time() (time.Time, "error":/docs/api/rest-sdk/types#error-info) - -Obtains the time from the Ably service as a @Time@ objecta @DateTimeOffset@ objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably "TokenRequests":/docs/api/rest-sdk/authentication#token-request with a more accurate timestamp should use the @queryTime@ "clientOptions":#client-options instead of this method). - -blang[jsall]. - h4. Returns - - Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an "@ErrorInfo@":#error-info object. - -blang[objc,swift]. - h4. 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@":#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation. - -blang[java,ruby,php,csharp]. - h4. Returns - - On success, milliseconds since epochthe @Time@the @DateTimeOffset@ is returned. - - Failure to retrieve the Ably server time will raise an "@AblyException@":/docs/api/rest-sdk/types#ably-exception. - -blang[go]. - h4. Returns - - On success, milliseconds since epochthe @Time@the @DateTimeOffset@ is returned. - - On failure to retrieve the Ably server time, @error@ contains an "@ErrorInfo@":#error-info object with an error response as defined in the "Ably REST API":/docs/api/rest-api#common documentation. - -<%= partial partial_version('rest/_request') %> - -blang[javascript]. - h6(#batchPublish). batchPublish - - There are two overloaded versions of this method: - - bq(definition#batchPublish). - default: batchPublish("BatchPublishSpec":#batch-publish-spec spec): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>> - - Publishes a "@BatchPublishSpec@":#batch-publish-spec object to one or more channels, up to a maximum of 100 channels. - - bq(definition#batchPublishArray). - default: batchPublish("BatchPublishSpec[]":#batch-publish-spec specs): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>[]> - - Publishes one or more "@BatchPublishSpec@":#batch-publish-spec objects to one or more channels, up to a maximum of 100 channels. - - h4. Parameters - - - spec := an object describing the messages to be batch published and to which channels
__Type: "@BatchPublishSpec@":#batch-publish-spec - - specs := an array of objects describing the messages to be batch published and to which channels
__Type: "@BatchPublishSpec@[]":#batch-publish-spec - - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object, or an array of "@BatchResult@":#batch-result objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as "@BatchPublishSuccessResult@":#batch-publish-success-result objects, whilst failures are "@BatchPublishFailureResult@":#batch-publish-failure-result objects. If an array of "@BatchResult@":#batch-result objects are returned, they are in the same order as the provided "@BatchPublishSpec@":#batch-publish-spec. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object. - - h6(#batchPresence). batchPresence - - bq(definition#batchPresence). - default: batchPresence(String[] channels): Promise<"BatchResult":#batch-result<"BatchPresenceSuccessResult":#batch-presence-success-result | "BatchPresenceFailureResult":#batch-presence-failure-result>[]> - - Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the "@clientId@":#client-options of members and their current "@PresenceAction@":/docs/api/rest-sdk/presence#presence-action. - - h4. Parameters - - - channels := an array of one or more channel names, up to a maximum of 100 channels
__Type: @String[]@__ - - h4. Returns - - Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as "@BatchPresenceSuccessResult@":#batch-presence-success-result objects, whilst failures are "@BatchPresenceFailureResult@":#batch-presence-failure-result objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object. - -h2(#related-types). Related types - -h3(#client-options). - default: ClientOptions - swift,objc: ARTClientOptions - java: io.ably.types.ClientOptions - csharp: IO.Ably.ClientOptions - flutter: ably.ClientOptions - -<%= partial partial_version('types/_rest_client_options_intro') %> -<%= partial partial_version('types/_client_options') %> -<%= partial partial_version('types/_rest_client_options') %> - -h3(#stats-type). - default: Stats object - swift,objc: ARTStats - java: io.ably.lib.types.Stats - ruby: Ably::Models::Stats - php: Ably\Models\Stats - csharp: IO.Ably.Stats - -<%= partial partial_version('types/_stats') %> - -h3(#stats-granularity). - objc,swift: ARTStatsGranularity - jsall: StatsIntervalGranularity - csharp: StatsIntervalGranularity - -<%= partial partial_version('types/_stats_granularity') %> - -h3(#http-paginated-response). - default: HttpPaginatedResponse - -<%= partial partial_version('types/_http_paginated_response') %> - -h3(#param). - java: io.ably.lib.types.Param - -blang[java]. - <%= partial partial_version('types/_param'), indent: 2, skip_first_indent: true %> - -blang[jsall]. - - h3(#batch-publish-spec). - jsall: BatchPublishSpec - - <%= partial partial_version('types/_batch_publish_spec') %> - - h3(#batch-result). - jsall: BatchResult - - <%= partial partial_version('types/_batch_result') %> - - h3(#batch-publish-success-result). - jsall: BatchPublishSuccessResult - - <%= partial partial_version('types/_batch_publish_success_result') %> - - h3(#batch-publish-failure-result). - jsall: BatchPublishFailureResult - - <%= partial partial_version('types/_batch_publish_failure_result') %> - - h3(#batch-presence-success-result). - jsall: BatchPresenceSuccessResult - - <%= partial partial_version('types/_batch_presence_success_result') %> - - h3(#batch-presence-failure-result). - jsall: BatchPresenceFailureResult - - <%= partial partial_version('types/_batch_presence_failure_result') %> diff --git a/src/pages/docs/api/rest-sdk.mdx b/src/pages/docs/api/rest-sdk.mdx new file mode 100644 index 0000000000..0967d0235c --- /dev/null +++ b/src/pages/docs/api/rest-sdk.mdx @@ -0,0 +1,1454 @@ +--- +title: Constructor +meta_description: "Client Library SDK REST API Reference constructor documentation." +meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, constructor" +redirect_from: + - /docs/api/versions/v1.1/rest-sdk + - /docs/api/versions/v1.0/rest-sdk + - /docs/api/versions/v0.8/rest-sdk +--- + +## Constructor + +The Ably REST library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/auth/basic) or [Token](/docs/auth/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 *)key(instancetype)initWithToken:(NSString *)token` + + + + + +`init(key: String)` + +`init(token: String)` + + + + + +`AblyRest(String api_key)` + + + + + +`ably.Rest(key: keyOrTokenIdString)` + + + + + +`ably.NewREST(ably.WithKey(key string)) (*RestClient, error)` + + + +This will instantiate the REST library with the provided API key or Token ID string. + + + +`new Ably.Rest(`[`ClientOptions`](#client-options)` clientOptions)` + + + + + +`Ably::Rest.new(`[`ClientOptions`](#client-options)` client_options)` + + + + + +`new Ably\AblyRest(`[`ClientOptions`](#client-options)` client_options)` + + + + + +`new io.ably.lib.AblyRest(`[`ClientOptions`](#client-options)` clientOptions)` + + + + + +`new IO.Ably.AblyRest(`[`ClientOptions`](#client-options)` clientOptions)` + + + + + +`- (instancetype)initWithOptions:(`[`ARTClientOptions`](#client-options)` *)options;` + + + + + +`init(options: `[`ARTClientOptions`](#client-options)`)` + + + + + +`AblyRest(`[`ClientOptions`](#client-options)` client_options)` + + + + + +`ably.Rest(options: `[`ClientOptions`](#client-options)` clientOptions)` + + + + + +`ably.NewREST(ably.WithKey(key string), ably.WithClientID(clientID string)) (*RestClient, error)` + + + + + +This will instantiate the library using the specified [`ClientOptions`](#client-options). + + + + + +This will instantiate the library and create a new `Ably::Rest::Client` using the specified [`ClientOptions`](#client-options). + + + + +The REST constructor is used to instantiate the library. The REST library may be instantiated multiple times with the same or different [`ClientOptions`](#client-options) 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](/docs/auth). + +#### Basic Authentication + +A private API key string for [`ClientOptions#key`](#client-options)[`ClientOptions#Key`](#client-options) or the constructor, as obtained from the [application dashboard](https://ably.com/dashboard), is required for [Basic Authentication](/docs/auth/basic). Use this option if you wish to use [Basic authentication](/docs/auth/basic), or if you want to be able to [request Ably Tokens](/docs/auth/token) without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a `key``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`](#client-options)[`ClientOptions#Token`](#client-options) 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 [`authUrl` and `authCallback` options](#client-options)[`:auth_url` and `:auth_callback` options](#client-options)[`auth_url` and `auth_callback` options](#client-options)[`AuthUrl` and `AuthCallback` options](#client-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``Key` or `Token`, and an initial token will be obtained automatically when required. + +Read more on [authentication](/docs/auth). + + + +### Thread safety + +The Cocoa SDK makes the following thread safety guarantees: + +* All public methods and properties can be safely accessed from any thread, both for reading and writing operations. +* Objects like `ARTTokenDetails` and message data returned by the SDK can be safely read from multiple threads. However, you should not modify these objects after they're created. +* Objects you pass to the library must not be mutated afterwards. Once passed to the SDK, treat them as immutable. You can safely read from them or pass them again, and the library will never modify them. + +All internal operations are dispatched to a single serial GCD queue to ensure thread safety within the SDK. You can specify a custom queue for this using `ARTClientOptions.internalDispatchQueue`, but it must be serial to maintain thread safety guarantees. + +All callbacks provided by you are dispatched to the main queue by default, allowing you to update UI directly without additional thread switching. You can specify a different queue using `ARTClientOptions.dispatchQueue`. The callback queue must be different from `ARTClientOptions.internalDispatchQueue` to prevent deadlocks. Using the same queue creates circular dependencies where internal operations wait for callbacks, while callbacks wait for the internal queue. + + + + +## AblyRest PropertiesAbly.Rest Propertiesio.ably.lib.AblyRest MembersAbly::Rest::Client AttributesARTRest Propertiesably.Rest Properties + +The REST client exposes the following public attributesmembersproperties: + +### authAuth + +A reference to the [`Auth`](/docs/api/rest-sdk/authentication) authentication object configured for this client library. + +### push + +A reference to the [`Push`](/docs/push)[`ARTPush`](/docs/push) object in this client library. + + + +### device + +A reference to the [`LocalDevice`](/docs/push/configure/device)[`ARTLocalDevice`](/docs/push/configure/device) object. + + + +### channelsChannels + +[`Channels`](/docs/channels) is a reference to the [`Channel`](/docs/channels) collection instance for this library indexed by the channel name. You can use the [`Get`](/docs/api/rest-sdk/channels#get) method of this to get a `Channel` instance. See [channels](/docs/channels) and [messages](/docs/channels/messages/) for more information. + +## AblyRest MethodsAbly.Rest Methodsio.ably.lib.AblyRest MethodsAbly::Rest::Client MethodsARTRest Methodsably.Rest Methods + +### statsStats + + + +`stats(Object params?): Promise>` + + + + + +`PaginatedResult stats(Hash options)` + + + + + +`PaginatedResult stats(kwargs_options)` + + + + + +`PaginatedResult stats(Array options)` + + + + + +`PaginatedResult stats(Param[] options)` + + + + + +`Task> StatsAsync(StatsRequestParams query)` + + + + + +`stats(query: ARTStatsQuery?, callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void) throws` + + + + + +`(c *RestClient) Stats(params *PaginateParams) (*PaginatedResult, error)` + + + + +This call queries the [REST `/stats` API](/docs/api/rest-api#stats) and retrieves your application's usage statistics. A [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result) is returned, containing an array of [`Stats`](#stats-type) for the first page of results. [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result) objects are iterable providing a means to page through historical statistics. [See an example set of raw stats returned via the REST API](/docs/metadata-stats/stats#metrics). + +See [statistics](/docs/metadata-stats/stats) for more information. + +#### Parameters + + + +| Parameter | Description | +|-----------|-------------| +| options | An optional Hash containing the query parameters | +| &block | Yields a `PaginatedResult` object | + + + + + +| Parameter | Description | +|-----------|-------------| +| query | An optional `ARTStatsQuery` containing the query parameters | +| callback | Called with a [`ARTPaginatedResult`](#paginated-result)`<`[`ARTStats`](/docs/api/rest-sdk/types#stats)`>` object or an error | + + + + + +| Parameter | Description | +|-----------|-------------| +| optionsqueryparams | An optional object`StatsRequestParams`[`Param[]`](#param) array containing the query parameters set of parameters used to specify which statistics are retrieved. If not specified the default parameters will be used | + + + +#### options parametersARTStatsQuery propertiesStatsRequestParams propertiesparams properties + +The following options, as defined in the [REST `/stats` API](/docs/api/rest-api#stats) endpoint, are permitted: + +| Parameter | Description | Type | Default | +|-----------|-------------|------|---------| +| start:startStart | Earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved | `Long``Int` or `Time``DateTimeOffset``Number` | beginning of time | +| end:endEnd | Latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved | `Long``Int` or `Time``DateTimeOffset``Number` | current time | +| direction:directionDirection | `:forwards` or `:backwards``forwards` or `backwards` | `String``Symbol``Direction` enum | backwards | +| limit:limitLimit | Maximum number of stats to retrieve up to 1,000 | `Integer``Number` | 100 | +| unit:unitUnit | `:minute`, `:hour`, `:day` or `:month`.`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`[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity)[`ARTStatsGranularity`](#stats-granularity)[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity) enum | minute | + + + +#### Returns + +Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result) object containing an array of [`Stats`](/docs/api/rest-sdk/types#stats) objects. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object. + + + + + +#### Callback result + +On success, `result` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Stats`](/docs/api/rest-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. + +On failure to retrieve stats, `err` contains an [`ErrorInfo`](#error-info) object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. + + + + + +#### Returns + +On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Stats`](/docs/api/rest-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. + +Failure to retrieve the stats will raise an [`AblyException`](/docs/api/rest-sdk/types#ably-exception) + + + + + +#### Returns + +The method is asynchronous and return Task which needs to be awaited. + +On success, the returned [`PaginatedResult`](#paginated-result) encapsulates a list of [`Stats`](/docs/api/rest-sdk/types#stats) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`NextAsync`](#paginated-result) and [`FirstAsync`](#paginated-result) methods. + +Failure to retrieve the stats will raise an [`AblyException`](/docs/api/rest-sdk/types#ably-exception) + + + + +### timeTime + + + +`time(): Promise` + + + + + +`Time time` + + + + + +`Int time()` + + + + + +`Integer time()` + + + + + +`long time()` + + + + + +`Task TimeAsync()` + + + + + +`time(callback: (NSDate?, NSError?) -> Void)` + + + + + +`(c *RestClient) Time() (time.Time, error)` + + + + +Obtains the time from the Ably service as a `Time` objecta `DateTimeOffset` objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request) with a more accurate timestamp should use the `queryTime` [`clientOptions`](#client-options) instead of this method). + + + +#### Returns + +Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object. + + + + + +#### 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`](#error-info) object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. + + + + + +#### Returns + +On success, milliseconds since epochthe `Time`the `DateTimeOffset` is returned. + +Failure to retrieve the Ably server time will raise an [`AblyException`](/docs/api/rest-sdk/types#ably-exception). + + + + + +#### Returns + +On success, milliseconds since epoch is returned. + +On failure to retrieve the Ably server time, `error` contains an [`ErrorInfo`](#error-info) object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. + + + + +### requestRequest + + + +`request(method, path, version, params?, body?, headers?): Promise` + + + + + +`HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)` + + + + + +`publish(method=String, path=String, params=Object, body=Object, headers=Object)` + + + + + +`HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)` + + + + + +`Task Request(string method, string path, Dictionary requestParams, JToken body, Dictionary headers)` + + + + + +`request(method: String, path: String, params: Object?, body: Object?, headers: Object?, callback: (ARTHttpPaginatedResponse, ARTErrorInfo?) -> Void)` + + + + + +`HTTPPaginatedResponse Request(method string, path string, params PaginateParams, body interface, headers http.Header)` + + + +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 | +| version | version of the REST API to use | Number | +| 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, such as an `Object` or `Array` | Serializable | +| headers | (optional) any headers needed. If provided, these will be mixed in with the default library headers | Object | + + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| method | either `get`, `post`, `put`, `patch` or `delete` | `string``String` | +| path | the path to query | `string``String` | +| params | (optional) any querystring parameters needed | `Dictionary``Object``PaginateParams` | +| body | (optional; for `post`, `put` and `patch` methods) the body of the request, as anything that can be serialized into JSON, as a JToken. | `Token``Serializable``interface` | +| headers | (optional) any headers needed. If provided, these will be mixed in with the default library headers | `Dictionary``Object``http.Header` | + + + + + +#### Returns + +Returns a promise. On success, the promise is fulfilled with the [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response) object returned by the HTTP request. The response object will contain an empty or JSON-encodable object. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object. + + + + + +#### Callback result + +On successfully receiving a response from Ably, `results` contains an `ARTHttpPaginatedResponse` containing the `statusCode` of the response, a `success` boolean (equivalent to whether the status code is between 200 and 299), `headers`, and an `items` array containing the current page of results. It supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods, identically to [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result). + +On failure to obtain a response, `err` contains an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with an error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. (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 `err`). + + + + + +#### Returns + +On successfully receiving a response from Ably, the returned [`HttpPaginatedResponse`](/docs/api/rest-sdk/types#http-paginated-response) contains a `status_code``statusCode` and a `success` boolean, `headers`, and an `items` array containing the current page of results. It supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods, identically to [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result). + +Failure to obtain a response will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). (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). + + + + + +#### Returns + +The method is asynchronous and return a Task that has to be awaited to get the result. + +On successfully receiving a response from Ably, the returned [`HttpPaginatedResponse`](/docs/api/rest-sdk/types#http-paginated-response) containing the `StatusCode` and a `Success` boolean, `Headers`, and an `Items` array containing the current page of results. [`HttpPaginatedResponse`](/docs/api/rest-sdk/types#http-paginated-response) supports pagination using [`NextAsync`](#paginated-result) and [`FirstAsync`](#paginated-result) methods. + +Failure to obtain a response will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). (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). + + + + + + +#### Example + + + + +```javascript +const response = await rest.request( + 'get', + '/channels/someChannel/messages', + 3, + { limit: 1, direction: 'forwards' }, +); +console.log('Success! status code was ' + response.statusCode); +console.log(response.items.length + ' items returned'); +if (response.hasNext()) { + const nextPage = await response.next(); + console.log(nextPage.items.length + ' more items returned'); +} +``` + + + + + + + +```nodejs +const response = await rest.request( + 'get', + '/channels/someChannel/messages', + 3, + { limit: 1, direction: 'forwards' }, +); +console.log('Success! status code was ' + response.statusCode); +console.log(response.items.length + ' items returned'); +if (response.hasNext()) { + const nextPage = await response.next(); + console.log(nextPage.items.length + ' more items returned'); +} +``` + + + + + + + + +### batchPublish + +There are two overloaded versions of this method: + +`batchPublish(BatchPublishSpec spec): Promise>` + +Publishes a [`BatchPublishSpec`](#batch-publish-spec) object to one or more channels, up to a maximum of 100 channels. + +`batchPublish(BatchPublishSpec[] specs): Promise[]>` + +Publishes one or more [`BatchPublishSpec`](#batch-publish-spec) objects to one or more channels, up to a maximum of 100 channels. + +#### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| spec | An object describing the messages to be batch published and to which channels | [`BatchPublishSpec`](#batch-publish-spec) | +| specs | An array of objects describing the messages to be batch published and to which channels | [`BatchPublishSpec[]`](#batch-publish-spec) | + +#### Returns + +Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#batch-result) object, or an array of [`BatchResult`](#batch-result) objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as [`BatchPublishSuccessResult`](#batch-publish-success-result) objects, whilst failures are [`BatchPublishFailureResult`](#batch-publish-failure-result) objects. If an array of [`BatchResult`](#batch-result) objects are returned, they are in the same order as the provided [`BatchPublishSpec`](#batch-publish-spec). On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object. + + +### batchPresence + +`batchPresence(String[] channels): Promise[]>` + +Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the [`clientId`](#client-options) of members and their current [`PresenceAction`](/docs/api/rest-sdk/presence#presence-action). + +#### Parameters + +| Parameter | Description | Type | +|-----------|-------------|------| +| channels | An array of one or more channel names, up to a maximum of 100 channels | `String[]` | + +#### Returns + +Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#batch-result) object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as [`BatchPresenceSuccessResult`](#batch-presence-success-result) objects, whilst failures are [`BatchPresenceFailureResult`](#batch-presence-failure-result) objects. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object. + + + + + +## Related types + +### ClientOptionsARTClientOptionsio.ably.types.ClientOptionsIO.Ably.ClientOptionsably.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: + + + + + +`ART``ClientOptions` is used in the `AblyRest` constructor's `options` argument. + + + + + +`ably.ClientOptions` is used in the `ably.Rest` constructor's `options` named argument + + + + + +#### PropertiesMembersAttributesKeyword arguments + +| Parameter | Description | Type | +|-----------|-------------|------| +| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | +| authUrlAuthUrl:auth_urlauth_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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | +| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | +| authHeadersAuthHeadersauth_headers: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. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Map` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``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. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| tlsTls: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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` 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 `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| idempotentRestPublishingIdempotentRestPublishing: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. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
_default: false_ | `Boolean` | +| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | +| logLevellog_level | A number controlling the verbosity of the log output of the library. 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). | `Integer` | +| logHandlerlog_handler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` | +| transports | An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: `web_socket`, `xhr_polling`. | `String[]` | +| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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` | +| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + + +#### Properties + +| Parameter | Description | Type | +|-----------|-------------|------| +| Key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| Token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| AuthCallback | 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 [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` | +| AuthUrl | 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String` | +| AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`
_default: `GET`_ | `String` | +| AuthHeaders | 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. | `Object` | +| AuthParams | 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. | `Object` | +| TokenDetails | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `ClientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: null_ | `String` | +| Environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: null_ | `String` | +| IdempotentRestPublishing | 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.
_default: false_ | `Boolean` | +| FallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` | +| LogLevel | A number controlling the verbosity of the log output of the library. 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). | `Integer` | +| UseBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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` | +| DefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + + + +#### Attributes + +| Parameter | Description | Type | +|-----------|-------------|------| +| :key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| :token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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](/docs/auth/token) | `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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#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 `:post`
_default: `: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`](/docs/api/realtime-sdk/types#token-details) 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](/docs/auth/token) | `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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-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](/docs/auth/identified-clients) | `String` | +| :use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| :endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nil_ | `String` | +| :environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nil_ | `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. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
_default: false_ | `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 a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| :transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Hash` | +| :log_level | A number controlling the verbosity of the log output of the library. 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). | `Integer` | +| :logger | A Ruby [`Logger`](http://ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) 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](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: true_ | `Boolean` | +| :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + + + +#### Keyword arguments + +| Parameter | Description | Type | +|-----------|-------------|------| +| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | +| authUrlAuthUrl:auth_urlauth_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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | +| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | +| authHeadersAuthHeadersauth_headers: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. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Map` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``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. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| tlsTls: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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` 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 `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| idempotentRestPublishingIdempotentRestPublishing: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. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
_default: false_ | `Boolean` | +| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | +| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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` | +| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + + +#### MembersPropertiesAttributes + +| Parameter | Description | Type | +|-----------|-------------|------| +| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | +| authUrlAuthUrl:auth_urlauth_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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | +| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | +| authHeadersAuthHeadersauth_headers: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. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Map` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``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. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| tlsTls: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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` 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 `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| idempotentRestPublishingIdempotentRestPublishing: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. We recommend you enable this by default. In version 1.2 onwards, idempotent publishing for retries will be enabled by default.
_default: false_ | `Boolean` | +| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | +| logLevellog_level | A number controlling the verbosity of the log output of the library. 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). | `Integer` | +| logHandlerlog_handler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` | +| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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` | +| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + + +#### Properties + +| Parameter | Description | Type | +|-----------|-------------|------| +| key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallback | 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 [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` | +| authUrl | 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String` | +| authMethod | The HTTP verb to use for the request, either `GET` or `POST`
_default: `GET`_ | `String` | +| authHeaders | 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. | `Map` | +| authParams | 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. | `Map` | +| tokenDetails | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` 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 `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: null_ | `String` | +| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: null_ | `String` | +| idempotentRestPublishing | 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.
_default: false_ | `Boolean` | +| fallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Map` | +| useBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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` | +| defaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + + + + +#### Properties + +| Parameter | Description | Type | +|-----------|-------------|------| +| Key | The full key string, as obtained from the [application dashboard](https://ably.com/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](/docs/auth/basic) | `String` | +| Token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token#jwt)). 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 `AuthUrl` or `AuthCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| AuthCallback | 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 [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Func>` | +| AuthUrl | 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`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `Uri` | +| AuthMethod | The HTTP verb to use for the request, either `GET` or `POST`
_default: `GET`_ | `HttpMethod` | +| AuthHeaders | 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. | `Dictionary` | +| AuthParams | 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. | `Dictionary` | +| TokenDetails | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) 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 `AuthUrl` or `AuthCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `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](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| ClientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `ClientId` 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 `ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `ClientId` specified here conflicts with the `ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| UseTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| Endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: null_ | `String` | +| Environment | Deprecated, use `Endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: null_ | `String` | +| IdempotentRestPublishing | 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.
_default: false_ | `Boolean` | +| FallbackHosts | 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](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| TransportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Dictionary` | +| LogLevel | A number controlling the verbosity of the log output of the library. 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). | `Integer` | +| LoggerSink | The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure.
_default: IO.Ably.DefaultLoggerSink_ | `ILoggerSink` | +| UseBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| QueryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), 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](https://en.wikipedia.org/wiki/Ntpd). 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` | +| DefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | + + + +### Stats object ARTStats io.ably.lib.types.Stats Ably::Models::Stats Ably\Models\Stats IO.Ably.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](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/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](https://www.rubydoc.info/gems/ably/Ably/Models/Stats) 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 + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| unit | The length of the interval that this statistic covers, such as `:minute`, `:hour`, `:day`, `:month``Minute`, `Hour`, `Day`, `Month``StatGranularityDay`, `StatGranularityMonth``'minute'`, `'hour'`, `'day'`, `'month'`. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| interval_granularityintervalGranularityintervalGranularity | Deprecated alias for `unit`; scheduled to be removed in version 2.x client library versions. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| intervalIdinterval_idIntervalId | The UTC time at which the time period covered by this `Stats` object starts. For example, an interval ID value of "2018-03-01:10" in a `Stats` object whose `unit` is `day` would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All `Stats` objects, except those whose `unit` is `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 `unit` by looking at the resolution of the `intervalId`. `Stats` objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02". | `String` | +| interval_timeIntervalTime | A `Time``DateTime``DateTimeOffset` object representing the parsed `intervalId``interval_id``IntervalId` (the UTC time at which the time period covered by this `Stats` object starts) | `Time``DateTime``DateTimeOffset` | +| allAll | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| apiRequestsapi_requestsApiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| channelsChannels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) | +| connectionsConnections | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ConnectionTypes) | +| inboundInbound | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| outboundOutbound | 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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| persistedPersisted | Messages persisted and later retrieved via the [history API](/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| tokenRequeststoken_requestsTokenRequests | Breakdown of Ably Token requests received via the Ably REST API. | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| pushPush | Detailed stats on push notifications, see [our Push documentation](/docs/push) for more details | `PushStats` | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| unit | The length of the interval that this statistic covers, such as `:minute`, `:hour`, `:day`, `:month``Minute`, `Hour`, `Day`, `Month``StatGranularityDay`, `StatGranularityMonth``'minute'`, `'hour'`, `'day'`, `'month'`. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| intervalGranularityintervalGranularityintervalGranularity | Deprecated alias for `unit`; scheduled to be removed in version 2.x client library versions. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| intervalIdinterval_idIntervalId | The UTC time at which the time period covered by this `Stats` object starts. For example, an interval ID value of "2018-03-01:10" in a `Stats` object whose `unit` is `day` would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All `Stats` objects, except those whose `unit` is `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 `unit` by looking at the resolution of the `intervalId`. `Stats` objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02". | `String` | +| allAll | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| apiRequestsapi_requestsApiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| channelsChannels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) | +| connectionsConnections | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ConnectionTypes) | +| inboundInbound | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| outboundOutbound | 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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| persistedPersisted | Messages persisted and later retrieved via the [history API](/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| tokenRequeststoken_requestsTokenRequests | Breakdown of Ably Token requests received via the Ably REST API. | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| pushPush | Detailed stats on push notifications, see [our Push documentation](/docs/push) for more details | `PushStats` | + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| unit | The length of the interval that this statistic covers, such as `:minute`, `:hour`, `:day`, `:month``Minute`, `Hour`, `Day`, `Month``StatGranularityDay`, `StatGranularityMonth``'minute'`, `'hour'`, `'day'`, `'month'`. | [`Stats::GRANULARITY`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats#GRANULARITY-constant)[`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) enum`ARTStatsGranularity``String` | +| intervalIdinterval_idIntervalId | The UTC time at which the time period covered by this `Stats` object starts. For example, an interval ID value of "2018-03-01:10" in a `Stats` object whose `unit` is `day` would indicate that the period covered is "2018-03-01:10 .. 2018-03-01:11". All `Stats` objects, except those whose `unit` is `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 `unit` by looking at the resolution of the `intervalId`. `Stats` objects covering an individual minute will have an interval ID indicating that time; for example "2018-03-01:10:02". | `String` | +| allAll | Aggregate count of both `inbound` and `outbound` message stats | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| apiRequestsapi_requestsApiRequests | Breakdown of API requests received via the Ably REST API | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| channelsChannels | Breakdown of channel related stats such as min, mean and peak channels | [`ResourceCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ResourceCount) | +| connectionsConnections | Breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections | [`ConnectionTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/ConnectionTypes) | +| inboundInbound | Statistics such as count and data for all inbound messages received over REST and Realtime connections, organized into normal channel messages or presence messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| outboundOutbound | 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 messages | [`MessageTraffic`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTraffic) | +| persistedPersisted | Messages persisted and later retrieved via the [history API](/docs/storage-history/history) | [`MessageTypes`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/MessageTypes) | +| tokenRequeststoken_requestsTokenRequests | Breakdown of Ably Token requests received via the Ably REST API. | [`RequestCount`](https://www.rubydoc.info/gems/ably/Ably/Models/Stats/RequestCount) | +| pushPush | Detailed stats on push notifications, see [our Push documentation](/docs/push) for more details | `PushStats` | + + + + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| appId | The ID of the Ably application the statistics relate to. | `String` | +| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial>` | +| inProgress | Optional. For entires that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` | +| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` | +| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` | + + + + + +### ARTStatsGranularityStatsIntervalGranularityStatsIntervalGranularity + + + +`StatsIntervalGranularity` is an enum specifying the granularity of a [Stats interval](/docs/api/rest-sdk/statistics#stats-type). + + + + +```javascript +const StatsIntervalGranularity = [ + 'minute', + 'hour', + 'day', + 'month' +] +``` + + + + + + +```nodejs +const StatsIntervalGranularity = [ + 'minute', + 'hour', + 'day', + 'month' +] +``` + + + + + + + +`ARTStatsGranularity` is an enum specifying the granularity of a [ARTStats interval](/docs/api/rest-sdk/statistics#stats-type). + + + + +```objc +typedef NS_ENUM(NSUInteger, ARTStatsGranularity) { + ARTStatsGranularityMinute, + ARTStatsGranularityHour, + ARTStatsGranularityDay, + ARTStatsGranularityMonth +}; +``` + + + + + + +```swift +enum ARTStatsGranularity : UInt { + case Minute + case Hour + case Day + case Month +} +``` + + + + + + + +`StatsIntervalGranularity` is an enum specifying the granularity of a [Stats interval](/docs/api/rest-sdk/statistics#stats-type). + + +```csharp +public enum StatsIntervalGranularity +{ + Minute, + Hour, + Day, + Month +} +``` + + + + + + +### HttpPaginatedResponse + +An `HttpPaginatedResponse` is a superset of [PaginatedResult](/docs/api/rest-sdk/types#paginated-result), 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](/docs/api/rest-sdk#request). + +#### PropertiesMembersAttributes + + + +| Property | Description | Type | +|----------|-------------|------| +| itemsItemsitems | Contains a page of results; for example, an array of [Message](#message) or [PresenceMessage](#presence-message) objects for a channel history request | `Array<>``List<>` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | + + + + +| 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` | + + + + +| Property | Description | Type | +|----------|-------------|------| +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | + + + +#### Methods + +##### firstFirst + + + +`first(): Promise` + +Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` for the first page of results. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + + + +`HttpPaginatedResponse first` + +Returns a new `HttpPaginatedResponse` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields an [HttpPaginatedResponse](/docs/api/realtime-sdk/types#http-paginated-response). + + + + + +`HttpPaginatedResponse first()` + +Returns a new `HttpPaginatedResponse` for the first page of results. + + + + + +`HttpPaginatedResponse first()` + +Returns a new `HttpPaginatedResponse` for the first page of results. + + + + + +`Task> FirstAsync()` + +Returns a new `HttpPaginatedResponse` for the first page of results. The method is asynchronous and returns a Task which needs to be awaited to get the [HttpPaginatedResponse](/docs/api/realtime-sdk/types#http-paginated-response). + + + + + +`HttpPaginatedResponse first()` + +Returns a new `HttpPaginatedResponse` for the first page of results. + + + + + +`first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)` + +Returns a new `HttpPaginatedResponse` for the first page of results. + + + + + +`First() (HttpPaginatedResponse, error)` + +Returns a new `HttpPaginatedResponse` for the first page of results. + + + + +##### hasNextHasNexthas_next?has_next + + + +`Boolean hasNext()` + + + + + +`Boolean has_next?` + + + + + +`Boolean hasNext()` + + + + + +`Boolean has_next()` + + + + + +`Boolean HasNext()` + + + + + +`Boolean hasNext()` + + + + + +`Boolean hasNext()` + + + + + +`HasNext() (bool)` + + + +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. + +##### isLastIsLastlast?is_last + + + +`Boolean isLast()` + + + + + +`Boolean last?` + + + + + +`Boolean isLast()` + + + + + +`Boolean is_last()` + + + + + +`Boolean IsLast()` + + + + + +`Boolean isLast()` + + + + + +`Boolean isLast()` + + + + + +`IsLast() (bool)` + + + +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. + +##### nextNext + + + +`next(callback(err, resultPage))` + + + + + +`next(): Promise` + +Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `null` is returned. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + + + +`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](/docs/api/realtime-sdk/types#deferrable) and yields an [HttpPaginatedResponse](/docs/api/realtime-sdk/types#http-paginated-response). + + + + + +`HttpPaginatedResponse next()` + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `null` is returned. + + + + + +`HttpPaginatedResponse next()` + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `None` is returned. + + + + + +`Task> NextAsync()` + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then a blank HttpPaginatedResponse will be returned. The method is asynchronous and return a Task which needs to be awaited to get the `HttpPaginatedResponse`. + + + + + +`HttpPaginatedResponse next()` + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `Null` is returned. + + + + + +`next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) -> Void)` + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `nil` is returned. + + + + + +`Next() (HttpPaginatedResponse, error)` + +Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `nil` is returned. + + + + + +##### current + + + +`current(): Promise` + + + + + +`current(): Promise` + + + +Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the current page of results. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. + + + +#### Example + +The `HttpPaginatedResponse` interface is a superset of `PaginatedResult`, see the [PaginatedResult example](/docs/api/rest-sdk/types/#paginated-result-example) + + + +### 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](/docs/api/realtime-sdk/history#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 + +| Property | Description | Type | +|----------|-------------|------| +| key | The key value | `String` | +| value | The value associated with the `key` | `String` | + + + + + +### BatchPublishSpec + +A `BatchPublishSpec` describes the messages that should be published by a batch publish operation, and the channels to which they should be published. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| channels | The names of the channels to publish the `messages` to | `String[]` | +| messages | An array of [Message](/docs/api/realtime-sdk/types#message) objects | [`Message[]`](/docs/api/realtime-sdk/types#message) | + +### BatchResult + +A `BatchResult` contains information about the results of a batch operation. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| successCount | The number of successful operations in the request | `Number` | +| failureCount | The number of unsuccessful operations in the request | `Number` | +| messages | An array of results for the batch operation (for example, an array of [BatchPublishSuccessResult](/docs/api/realtime-sdk/types#batch-publish-success-result) or [BatchPublishFailureResult](/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` | + +### BatchPublishSuccessResult + +A `BatchPublishSuccessResult` contains information about the result of successful publishes to a channel requested by a single [BatchPublishSpec](/docs/api/realtime-sdk/types#batch-publish-spec). + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| channel | The name of the channel the message(s) was published to | `String` | +| messageId | A unique ID prefixed to the `Message.id` of each published message | `String` | + +### BatchPublishFailureResult + +A `BatchPublishFailureResult` contains information about the result of unsuccessful publishes to a channel requested by a single [BatchPublishSpec](/docs/api/realtime-sdk/types#batch-publish-spec). + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| channel | The name of the channel the message(s) failed to be published to | `String` | +| error | Describes the reason for which the message(s) failed to publish to the channel as an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | + +### BatchPresenceSuccessResult + +A `BatchPresenceSuccessResult` contains information about the result of a successful batch presence request for a single channel. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| channel | The channel name the presence state was retrieved for | `String` | +| presence | An array of [PresenceMessage](/docs/api/realtime-sdk/types#presence-message) describing members present on the channel | [`PresenceMessage[]`](/docs/api/realtime-sdk/types#presence-message) | + +### BatchPresenceFailureResult + +A `BatchPresenceFailureResult` contains information about the result of an unsuccessful batch presence request for a single channel. + +#### Properties + +| Property | Description | Type | +|----------|-------------|------| +| channel | The channel name the presence state failed to be retrieved for | `String` | +| error | Describes the reason for which presence state could not be retrieved for the channel as an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | + +