HTTP client
The HTTP client is the entry point for using the Ably Pub/Sub JavaScript SDK from a backend service over HTTP. It is a stateless client that makes a request to the Ably REST API for each operation, without maintaining a persistent connection, and provides access to channels, presence, push notifications, and authentication. Use it for server-side work that doesn't need realtime updates, such as publishing messages, issuing tokens, or retrieving history.
1
2
3
import { createHttpClient } from '@ably/pubsub-server';
const pubsubHttpClient = createHttpClient({ key: process.env.ABLY_API_KEY });This example uses basic authentication with an API key, which is appropriate for a backend service you operate. Code that runs on an end user's device uses the device client instead.
Properties
The HTTP client has the following properties:
The Crypto, Message, PresenceMessage and Annotation helpers are not properties of the client. Import them by name from @ably/pubsub-server.
Create a new HTTP client
Use createHttpClient() from the @ably/pubsub-server package to create an HTTP client in a backend service that you operate. Don't use @ably/pubsub-server in code that runs on an end user's device.
createHttpClient(options: ClientOptions): PubSubHttpClientCreate a client with a ClientOptions object. This is the most common form, allowing all available client options to be configured.
createHttpClient(keyOrToken: string): PubSubHttpClientA convenience form that takes a single API key or token string. Equivalent to passing { key: '<key>' } or { token: '<token>' } as ClientOptions.
The following example creates an HTTP client in a backend service:
1
2
3
4
5
6
7
8
9
10
import { createHttpClient } from '@ably/pubsub-server';
// With ClientOptions
const pubsubHttpClient = createHttpClient({
key: process.env.ABLY_API_KEY,
logLevel: 3
});
// Or with just a key string
const pubsubHttpClient = createHttpClient(process.env.ABLY_API_KEY);Parameters
createHttpClient() takes the following parameters:
optionsrequiredClientOptionskeyOrTokenrequiredStringGet server time
pubsubHttpClient.time(): Promise<number>Returns the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well-maintained time source and wish to issue Ably TokenRequests with a more accurate timestamp should use the clientOptions.queryTime client option instead of this method.
1
const now = await pubsubHttpClient.time();Returns
Promise<number>
Returns a promise. The promise is fulfilled with the server time as milliseconds since the Unix epoch, or rejected with an ErrorInfo object.
Get account stats
pubsubHttpClient.stats(params?: StatsParams): Promise<PaginatedResult<Stats>>Retrieves usage statistics for the account, filtered by the supplied query parameters. Returns a paginated set of Stats objects, each containing usage metrics.
1
const page = await pubsubHttpClient.stats({ unit: 'hour', limit: 24 });Parameters
The stats() method takes the following parameters:
paramsoptionalStatsParamsReturns
Promise<PaginatedResult<Stats>>
Returns a promise. The promise is fulfilled with a PaginatedResult of Stats objects, or rejected with an ErrorInfo object.
Stats
Each Stats entry contains the following properties:
appIdStringintervalIdStringunit was requested as minute this is in the format YYYY-mm-dd:HH:MM, if hour it is YYYY-mm-dd:HH, if day it is YYYY-mm-dd:00, and if month it is YYYY-mm-01:00.inProgressStringyyyy-mm-dd:hh:mm:ss.entriesRecord<String, Number>messages.all.count, messages.inbound.rest.count) to their values. The schema property provides further information.schemaStringMake a REST request
pubsubHttpClient.request(method: string, path: string, version: number, params?: any, body?: any, headers?: any): Promise<HttpPaginatedResponse>Makes a REST request to a provided path. Useful for accessing Ably APIs that do not have a dedicated method in the SDK, without having to handle authentication, paging, fallback hosts, and MsgPack or JSON support yourself.
1
2
3
4
5
6
const response = await pubsubHttpClient.request(
'GET',
'/channels/arc-one-ego/messages',
3,
{ limit: 10 }
);Parameters
The request() method takes the following parameters:
methodrequiredStringGET, POST, PUT, PATCH, DELETE).pathrequiredStringversionrequiredNumber3).paramsoptionalObjectbodyoptionalAnyPOST, PUT, and PATCH methods only. Must be anything that can be serialized into JSON, such as an object or array.headersoptionalObjectReturns
Promise<HttpPaginatedResponse>
Returns a promise. The promise is fulfilled with an HttpPaginatedResponse, or rejected with an ErrorInfo object. Note that if a response is obtained, any response, even one with a non-2xx status code, resolves as an HttpPaginatedResponse rather than rejecting.
HttpPaginatedResponse
HttpPaginatedResponse contains the following properties:
statusCodeNumbersuccessBooleantrue if the status code is in the 200-299 range.errorCodeNumberX-Ably-Errorcode HTTP header, if sent in the response.errorMessageStringX-Ably-Errormessage HTTP header, if sent in the response.errorDetailObject or UndefinedheadersObjectitemsArrayHttpPaginatedResponse also contains the following methods to handle pagination:
Check for more pages
hasNext(): booleanReturns true if there are more pages available by calling next().
Check if last page
isLast(): booleanReturns true if this is the last page of results.
Get next page
next(): Promise<PaginatedResult | null>Returns a promise. The promise is fulfilled with the next page of results as a PaginatedResult, or null if there are no more pages. Rejected with an ErrorInfo object on failure.
Get first page
first(): Promise<PaginatedResult>Returns a promise. The promise is fulfilled with the first page of results as a PaginatedResult, or rejected with an ErrorInfo object.
Get current page
current(): Promise<PaginatedResult>Returns a promise. The promise is fulfilled with the current page of results as a PaginatedResult, or rejected with an ErrorInfo object.
Batch publish to multiple channels
pubsubHttpClient.batchPublish(spec: BatchPublishSpec): Promise<BatchResult>Publish using a single BatchPublishSpec, fulfilled with a single BatchResult.
pubsubHttpClient.batchPublish(specs: BatchPublishSpec[]): Promise<BatchResult[]>Publish using an array of BatchPublishSpec objects, fulfilled with one BatchResult per spec.
Each spec publishes one or more messages to up to 100 channels in a single batch publish request.
1
2
3
4
const result = await pubsubHttpClient.batchPublish({
channels: ['channel1', 'channel2'],
messages: [{ name: 'event', data: 'hello' }]
});Parameters
The batchPublish() method takes the following parameters:
specrequiredBatchPublishSpecspecsrequiredBatchPublishSpec[]Returns
Promise<BatchResult | BatchResult[]>
Returns a promise. For a single spec, the promise is fulfilled with a BatchResult. For an array of specs, the promise is fulfilled with an array of BatchResults. Rejected with an ErrorInfo object on failure.
successCountNumberfailureCountNumberresultsArray of BatchPublishSuccessResult or BatchPublishFailureResultBatch presence query
pubsubHttpClient.batchPresence(channels: string[]): Promise<BatchResult[]>Retrieves the presence set for up to 100 channels in a single REST request. The presence state includes the clientId of members and their current presence action.
Parameters
The batchPresence() method takes the following parameters:
channelsrequiredString[]Returns
Promise<BatchResult[]>
Returns a promise. The promise is fulfilled with an array of BatchResult objects, one per channel, where each results entry is a BatchPresenceSuccessResult or a BatchPresenceFailureResult. Rejected with an ErrorInfo object on failure.
successCountNumberfailureCountNumberresultsArray of BatchPresenceSuccessResult or BatchPresenceFailureResultPaginatedResult
A PaginatedResult represents a page of results from a paginated query such as stats(), channel.history(), presence.history(), or channel.getMessageVersions().
Properties
PaginatedResult contains the following properties:
itemsArrayPaginatedResult also contains the following methods to handle pagination:
Check for more pages
hasNext(): booleanReturns true if there are more pages available.
Check if last page
isLast(): booleanReturns true if this is the last page of results.
Get next page
next(): Promise<PaginatedResult | null>Returns a promise fulfilled with the next page of results, or null if there are no more pages. Rejected with an ErrorInfo object on failure.
Get first page
first(): Promise<PaginatedResult>Returns a promise fulfilled with the first page of results, or rejected with an ErrorInfo object.
Get current page
current(): Promise<PaginatedResult>Returns a promise fulfilled with the current page of results, or rejected with an ErrorInfo object.
ErrorInfo
A standardized, generic Ably error object that contains an Ably-specific error code, a generic HTTP status code, and a human-readable message. All errors emitted by Ably are ErrorInfo instances.
codeNumberstatusCodeNumbermessageStringcauseErrorInfo or UndefineddetailObject or UndefinedremediationString or Undefinedmessage, which describes what went wrong. Present only on SDK-originating errors with meaningful remediation steps.