Warning: You are viewing an old version (1.0) of this documentation. We recommend you view the latest version 1.2.
API Reference

REST API Specification

Channel routes

Routes providing access to the messaging service within a channel scope.

Publish one or more messages on a channel

POST rest.ably.io/channels/<channelId>/messages

Publish a message on a channel. Note that since the REST API is stateless, publication using this API is outside the context of any specific connection.

The request body contains message details and is an object of the form:

{
  name: <event name>,
  data: <message payload>,
  encoding: <optional encoding>,
  clientId: <optional explicit client identifier>,
  connectionKey: <optional private connection key>,
  extras: <optional, see below>
}

In JSON format, the accepted types for the data payload are:

  • string
  • any JSON-encodable Array or Object.

MessagePack additionally supports byte arrays

A message may be published over REST on behalf of an existing realtime connection when a valid connectionKey is present. For example, if you want to publish a message using the REST API so that it appears to come from an existing connected realtime client, then the connection’s private (secret) connection key must be included. See a publish on behalf of a realtime client example.

Example request:

curl -X POST https://rest.ably.io/channels/rest-example/messages \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU" \
 -H "Content-Type: application/json" \
 --data '{ "name": "publish", "data": "example" }'
Message extras

Messages can include an optional extras field, used by extensions to Ably’s core realtime service.

Send push notification

You can send a push notification to devices subscribed to the channel the message is sent to by setting the @[email protected] field in the extras object, like this:

{
  <... message fields ...>
  extras: {
    push: {
      data: <arbitrary key-value string-to-string payload>,
      notification: {
        title: <string, title to display at the notification>,
        body: <string, text below title on the expanded notification>,
        icon: <string, platform-specific>,
        sound: <string, platform-specific>,
        collapseKey: <string, platform-specific, used to group notifications together>
      }
      apns: <optional, extends and overrides generic values when delivering via APNs>,
      fcm: <optional, extends and overrides generic values when delivering via GCM/FCM>,
      web: <optional, extends and overrides generic values when delivering via web>
    }
  }
}

For each underlying transport service (like APNs, FCM/GCM, etc.) an object can be provided with the same shape as the parent object, plus any transport-specific field you may want to add (e. g. content-available for APNs).

Full example of a request publishing a message with a push payload:

curl -X POST https://rest.ably.io/channels/push-enabled:rest-example/messages \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU" \
 -H "Content-Type: application/json" \
 --data \
 '
{
  "name": "some event name for realtime receivers",
  "data": "example non-push data for realtime receivers",
  "extras": {
    "push": {
      "notification": {
        "title": "Hello from Ably!",
        "body": "Example push notification from Ably."
      },
      "data": {
        "foo": "bar",
        "baz": "qux"
      },
      "apns": {
        "notification": {
          "content-available": 1,
          "sound": "ably-ios.wav"
        }
      }
    }
  }
}
'
Parameters

None

Options
Content-Type
application/json, application/x-msgpack or application/x-www-form-urlencoded
Accept
not applicable
Auth required
yes (basic or token)
Returns

Nothing when successful, else returns an error.

Retrieve message history for a channel

GET rest.ably.io/channels/<channelId>/messages

If a channel is configured to persist messages, then all messages on that channel, within your account retention period, are available via this API endpoint. If persistence is not configured, then there are no guarantees as to how many historical messages will be available for the channel. Find out more about message persistence.

Example request:

curl https://rest.ably.io/channels/rest-example/messages \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
start
beginning of time The start of the query interval as a time in milliseconds since the epoch. A message qualifies as a member of the result set if it was received at or after this time.
end
now The end of the query interval as a time in milliseconds since the epoch. A message qualifies as a member of the result set if it was received at or before this time.
limit
100 The maximum number of records to return. A limit greater than 1,000 is invalid.
direction
backwards The direction of this query. The direction determines the order of the returned result array, but also determines which end of the query interval is the start point for the search. For example, a forwards query uses start as the start point, whereas a backwards query uses end as the start point.
Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token)
Returns

In each case a successful result is a paginated response with an array containing the items that match the query (and it may be empty).

[{
  id: <unique message id>
  name: <event name>,
  data: <message payload>,
  timestamp: <message timestamp in ms since epoch>
}]

Retrieve instantaneous presence status for a channel

GET rest.ably.io/channels/<channelId>/presence

Obtain the set of members currently present for a channel.

Example request:

curl https://rest.ably.io/channels/rest-example/presence \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
clientId
optional filter to restrict members present with that clientId
connectionId
optional filter to restrict members present with that connectionId
limit
100 The maximum number of records to return. A limit greater than 1,000 is invalid.
Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token)
Returns

A successful request returns a paginated response with an array containing the members that are currently present on the given channel. If there are no members present, an empty collection is returned.

[{
  id: <a unique member identifer generated by Ably>,
  clientId: <member client id provided by the client>,
  connectionId: <a unique connection id generated by Ably>
  timestamp: <message timestamp in ms since epoch>
  action: <presence state>,
  data: <optional clientData provided by the client>
}]

Retrieve presence state history for a channel

GET rest.ably.io/channels/<channelId>/presence/history

Obtain the history of presence messages for a channel.

Example request:

curl https://rest.ably.io/channels/rest-example/presence/history \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
start
beginning of time The start of the query interval as a time in milliseconds since the epoch. A message qualifies as a member of the result set if it was received at or after this time.
end
now The end of the query interval as a time in milliseconds since the epoch. A message qualifies as a member of the result set if it was received at or before this time.
limit
100 The maximum number of records to return. A limit greater than 1,000 is invalid.
direction
backwards The direction of this query. The direction determines the order of the returned result array, but also determines which end of the query interval is the start point for the search. For example, a forwards query uses start as the start point, whereas a backwards query uses end as the start point.
Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token)
Returns

A successful request returns a paginated response with an array containing the members that are currently present on the given channel. If there are no members present, an empty collection is returned.

[{
  id: <a unique member identifer generated by Ably>,
  clientId: <member client id provided by the client>,
  connectionId: <a unique connection id generated by Ably>
  timestamp: <message timestamp in ms since epoch>
  action: <presence state>,
  data: <optional clientData provided by the client>
}]

Retrieve metadata for a channel

This returns a ChannelDetails for the given channel, indicating global occupancy. A side-effect of this request, in this pre-release of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the enumeration API or in situations where the application has another means to know whether or not a given channel is active. A future version of this API will remove that restriction.

Example request:

curl https://rest.ably.io/channels/<channelId> \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"

The credentials presented with the request must include the channel-metadata permission for the channel in question.

Client libraries currently do not support this API, but it is usable via the generic request API.

It is worth noting that occupancy is currently only available to our enterprise customers. However, you can still try and test out the occupancy events using your free account.

Enumerate all active channels

This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the Ably REST library.

Example request:

curl https://rest.ably.io/channels \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"

This will return either a list of channel names, or a ChannelDetails object depending on what options you’ve specified.

The following parameters are supported:

limit
100 optionally specifies the maximum number of results to return. A limit greater than 1000 is unsupported
Type: integer
prefix
optionally limits the query to only those channels whose name starts with the given prefix
Type: string
by
value optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)

The credentials presented with the request must include the channel-metadata permission for the wildcard resource (‘*’) or, if a prefix is specified, for a resource that matches the prefix.

Client libraries currently do not provide a dedicated API to enumerate channels, but make this available using the request method. When using this, you can simply iterate through the PaginatedResults to enumerate through the results.

Enumeration is possible of all channels in an app, by repeated calls to the API, following the next relative link on each successive call, until there is no next relative link. However, the state of the app and the cluster itself can change during that enumeration. This API therefore has the following limitations:

  • channels that become active, or become inactive, between the first and last request in the sequence, might or might not appear in the result. The API guarantees that if a channel is continuously active from the time that the first request is made until the time that the last request completes, then it is guaranteed to be present in the result. Similarly, if a channel is continously inactive between those times then it is guaranteed not to be present in the result
  • cluster state changes, in this first release of this API, may cause a pagination sequence to become invalid, in which case the request will respond with an error with code 40011. In this case, to get a complete result, it is necessary to start the enumeration again from the beginning. Other API options to deal with this possibility will be provided in later versions of this API. Enumerations that are satisfiable in the first response page do not have this issue.

Push

Register a device for receiving push notifications

Register a device’s details, including the information necessary to deliver push notifications to it.

POST rest.ably.io/push/deviceRegistrations

The request body contains device and push recipient details, and is an object of the form:

{
  id: <string>,
  clientId: <optional, string, client identifier to associate with registration>,
  platform: <string, one of ios, android or browser>,
  formFactor: <string, one of phone, tablet, desktop, tv, watch, car or embedded>,
  metadata: <optional, object, with flexible key/value string pairs>,
  push: {
    recipient: {
      transportType: <string, one of gcm, fcm, apns or web>,
      <additional key/value string pairs for transport-specific recipient address>
    }
  }
}

The recipient address attributes are necessary and vary by underlying transport service.

For APNs:

{
  deviceToken: <string>
}

For GCM/FCM:

{
  registrationToken: <string>
}

For web:

{
  targetUrl: <string>
  encryptionKey: <string>
}

Example request:

curl -X POST https://rest.ably.io/push/deviceRegistrations \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
 -H "Content-Type: application/json" \
 --data \
'{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "platform": "ios",
  "formFactor": "phone",
  "push": {
    "recipient": {
      "transportType": "apns",
      "deviceToken": "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad"
    }
  }
}'
Parameters

None

Options
Content-Type
application/json, application/x-msgpack or application/x-www-form-urlencoded
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-subscribe or push-admin capability; when registering for a client ID with a push-subscribe capability, the token must be associated with that client ID)

A successful request returns the just-registered device details. It includes an updateToken, which is a token that can be used by typically a mobile device to authenticate with Ably later and update an existing device registration (for example, for updating a GCM or FCM registration token).

An unsuccessful request returns an error.

Update a device registration

Device registrations can be either upserted (the existing registration is replaced entirely) with a PUT operation, or specific attributes of an existing registration can be updated using a PATCH operation:

PUT rest.ably.io/push/deviceRegistrations/<deviceId>

The body must have the same shape as when registering the device. The PUT operation will replace the existing device registration, however please bear in mind that a registered device in Ably is largely immutable. As such, only the following attributes are currently updatable and any attempt to modify other fields will result in the update failing:

  • clientId
  • metadata
  • push.recipient

Additionally, if the push.state or updateToken attributes are provided, they will be accepted if they match the existing value. However if they differ (and are not null or omitted), then the update will fail.

If you need to make changes to any other fields, you will have to deregister the existing device and then register a new one.

Example request:

curl -X PUT https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
 -H "Content-Type: application/json" \
 --data \
'{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "platform": "ios",
  "formFactor": "phone",
  "metadata": {
    "timezone": "PST"
  },
  "push": {
    "recipient": {
      "transportType": "apns",
      "deviceToken": "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad"
    }
  }
}'
Parameters

None

Options
Content-Type
application/json, application/x-msgpack or application/x-www-form-urlencoded
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability)

A successful request returns the updated device details.

An unsuccessful request returns an error.

PATCH rest.ably.io/push/deviceRegistrations/<deviceId>

The body must have the same shape as when registering the device, except only fields to be changed should be provided. Any fields provided replace existing values. Please bear in mind that fields whose values are structured (JSON-like arrays or objects) types will replace existing values as opposed to be merged into existing values. metadata and push.recipient are examples of these types. Currently only the following attributes are currently updatable and any attempt to modify other fields will result in the update failing:

  • clientId (this field is only editable with a push-admin capability)
  • metadata (this field is only editable with a push-admin capability)
  • push.recipient

If you need to make changes to any other fields, you will have to deregister the existing device and then register a new one.

Example request:

curl -X PATCH https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
 -H "Content-Type: application/json" \
 --data \
'{
  "metadata": {
    "myKey": "value"
  }
 }'
Parameters

None

Options
Content-Type
application/json, application/x-msgpack or application/x-www-form-urlencoded
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability, or token authentication using the device’s update token)

A successful request returns the updated device details.

An unsuccessful request returns an error.

Get details from a registered device

GET rest.ably.io/push/deviceRegistrations/<deviceId>

Obtain the details for a device registered for receiving push registrations.

Example request:

curl https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters

None.

Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability)
Returns

A JSON object like:

{
  id: <string>,
  clientId: <optional, string>
  platform: <string>
  formFactor: <string>,
  metadata: <object>,
  updateToken: <string>,
  push: {
    recipient: {
      transportType: <string>,
      <additional recipient address key/value pairs>
    },
    state: <active or failed>
  }
}

or a 404 error if a device by that ID does not exist.

List registered devices

GET rest.ably.io/push/deviceRegistrations

Obtain the details for devices registered for receiving push registrations.

Example request:

curl https://rest.ably.io/push/deviceRegistrations \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
deviceId
optional filter to restrict to devices associated with that deviceId
clientId
optional filter to restrict to devices associated with that clientId
limit
100 The maximum number of records to return. A limit greater than 1,000 is invalid.
Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability)
Returns

A successful request returns a paginated response of:

[{
  id: <string>,
  clientId: <optional, string>
  platform: <string>
  formFactor: <string>,
  metadata: <object>,
  updateToken: <string>,
  push: {
    recipient: {
      transportType: <string>,
      <additional recipient address key/value pairs>
    },
    state: <active or failed>
  }
}]

Reset a registered device’s update token

POST rest.ably.io/push/deviceRegistrations/<deviceId>/resetUpdateToken

Example request:

curl -X POST https://rest.ably.io/push/01ARZ3NDEKTSV4RRFFQ69G5FAV/resetUpdateToken \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters

None

Options
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability, or token authentication using the device’s update token)

A successful request returns the updated device details.

A unsuccessful request returns an error.

Unregister a single device for push notifications

DELETE rest.ably.io/push/deviceRegistration/<deviceId>

Unregisters a single device by its device ID. All its subscriptions for receiving push notifications through channels will also be deleted.

Please note that this operation is done asynchronously so immediate requests subsequent to this delete request may briefly still return the device.

Example request:

curl -X DELETE \
 https://rest.ably.io/push/deviceRegistrations/01ARZ3NDEKTSV4RRFFQ69G5FAV \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters

None

Options
Content-Type
not applicable
Auth required
yes (basic or token with push-admin capability)
Returns

A successful request returns an empty response.

An unsuccessful request returns an error.

Unregister matching devices for push notifications

DELETE rest.ably.io/push/deviceRegistrations

Unregisters devices. All their subscriptions for receiving push notifications through channels will also be deleted.

Please note that this operation is done asynchronously so immediate requests subsequent to this delete request may briefly still return the device.

Example request:

curl -X DELETE \
 https://rest.ably.io/push/deviceRegistrations?deviceId=01ARZ3NDEKTSV4RRFFQ69G5FAV \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
deviceId
Filter to restrict to subscriptions for that deviceId. Cannot be used with clientId.
clientId
Filter to restrict to subscriptions associated with that clientId. Cannot be used with deviceId.
Options
Content-Type
not applicable
Auth required
yes (basic or token with push-admin capability)
Returns

A successful request returns an empty response.

An unsuccessful request returns an error.

Subscribe to a channel

Subscribe either a single device or all devices associated with a client ID to receive push notifications from messages sent to a channel.

POST rest.ably.io/push/channelSubscriptions

The request body contains subscription details and is an object of the form:

{
  channel: <string>,
  deviceId: <optional, string, must be set when clientId is empty, cannot be used with clientId>,
  clientId: <optional, string, must be set when deviceId is empty, cannot be used with deviceId>
}
curl -X POST https://rest.ably.io/push/channelSubscriptions \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
 -H "Content-Type: application/json" \
 --data \
 '
{
  "channel": "rest-example",
  "deviceId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}
'
Parameters

None

Options
Content-Type
application/json, application/x-msgpack or application/x-www-form-urlencoded
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-subscribe or push-admin capability; when subscribing for a client ID with a push-subscribe capability, the token must be associated with that client ID)

A successful request returns an empty object.

A unsuccessful request returns an error.

Unsubscribe from push notifications for channels

DELETE rest.ably.io/push/channelSubscriptions

Stop receiving push notifications when push messages are published on the specified channels.

Please note that this operation is done asynchronously so immediate requests subsequent to this delete request may briefly still return the subscription.

Example request:

curl -X DELETE \
 https://rest.ably.io/push/channelSubscriptions?deviceId=01ARZ3NDEKTSV4RRFFQ69G5FAV \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
channel
string, optional. If not set, all subscriptions on all channels will be deleted.
deviceId
Filter to restrict to subscriptions for that deviceId. Cannot be used with clientId.
clientId
Filter to restrict to subscriptions associated with that clientId. Cannot be used with deviceId.
Options
Content-Type
not applicable
Auth required
yes (basic or token with push-subscribe or push-admincapability; when deleting by client ID with a push-subscribe capability, the token must be associated with that client ID)
Returns

A successful request returns an empty response.

An unsuccessful request returns an error.

List channel subscriptions

GET rest.ably.io/push/channelSubscriptions

Get a list of push notification subscriptions to channels.

Example request:

curl https://rest.ably.io/push/channelSubscriptions \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters
channel
Filter to restrict to subscriptions associated with that channel.
clientId
Filter to restrict to subscriptions associated with that clientId. Cannot be used with deviceId.
deviceId
Filter to restrict to subscriptions for that deviceId. Cannot be used with clientId.
limit
100 The maximum number of records to return. A limit greater than 1,000 is invalid.
Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability)
Returns

A successful request returns a paginated response of:

[{
  channel: <string>,
  clientId: <string, only present when deviceId is not present>
  deviceId: <string, only present when clientId is not present>,
}]

List all channels with at least one subscribed device

GET rest.ably.io/push/channels

Example request:

curl https://rest.ably.io/push/channels \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"
Parameters

None

Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token with push-admin capability)
Returns

A successful request returns a paginated response of:

[<string, channel name>]

Publish a push notification to a single device

Convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their client identifier.

If you want to send a push notification to multiple devices or use a more flexible publish-subscribe architecture so that you don’t need to know about recipient devices’s details, we recommend you look at registering devices for push, then subscribe them to channels, and then send messages to the channels with push payloads.

This direct publish endpoint is designed for customers who typically have legacy devices they wish to push directly to, or if they want to publish to all devices for a single user.

POST rest.ably.io/push/publish

The request body is an object of the form:

{
  recipient: <object>
  <... rest of the fields just like a normal push-enabled message's extras.push object ...>
}

Example request:

curl -X POST https://rest.ably.io/push/publish \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU" \
 -H "Content-Type: application/json" \
 --data \
 '
{
  "recipient": {
    "clientId": "myClientId"
  },
  "notification": {
    "title": "Hello from Ably!",
    "body": "Example push notification from Ably."
  },
  "data": {
    "foo": "bar",
    "baz": "qux"
  }
}'

The recipient field supports delivering either to devices registered to Ably by device ID, by their associated client ID, or directly to devices using the underlying notifications service (GCM, APNs, etc.), thus bypassing registrations to Ably altogether.

By device ID:

{
  deviceId: <string>
}

By client ID:

{
  clientId: <string>
}

For APNs devices:

{
  transportType: "apns",
  deviceToken: <string>
}

For GCM/FCM devices:

{
  transportType: <fcm, gcm>,
  registrationToken: <string>
}

For web:

{
  transportType: "web",
  targetUrl: <string>,
  encryptionKey: <string>
}

The rest of the fields are normal push-enabled Ably message’s push.extras object.

Parameters

None

Options
Content-Type
application/json, application/x-msgpack or application/x-www-form-urlencoded
Accept
not applicable
Auth required
yes (basic or token with push-admin capability)

A successful request returns an empty response.

An unsuccessful request returns an error.

Authentication

Request an access token

POST rest.ably.io/keys/<keyName>/requestToken

This is the means by which clients obtain access tokens to use the service. The construction of an Ably TokenRequest is described in the Authentication Ably TokenRequest spec documentation. The resulting token response object contains the token properties as defined in Ably TokenRequest spec.

Example request:

curl -X POST "https://rest.ably.io/keys/xVLyHw.w4AJFg/requestToken" \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU" \
 -H "Content-Type: application/json" \
 --data '{ "keyName": "xVLyHw.w4AJFg", "timestamp": _VAR_MS_SINCE_EPOCH_VAR_ }'
Parameters

None

Options
Request body
signed or unsigned Ably TokenRequest. All Ably TokenRequests require values for keyName and timestamp attributes. In addition, signed Ably TokenRequests require values for attributes nonce and mac.
Content-Type
text/plain
Accept
application/json by default, or application/x-msgpack
Auth required
no (for signed Ably TokenRequests), yes (for unsigned Ably TokenRequests, basic or token permitted)
Returns

A successful request will return a token details object containing the token string.

{
  "token": "xVLyHw.CLchevH3hF....MDh9ZC_Q", // token string
  "keyName": "xVLyHw.mDYnFA",
  "issued": 1428356667,
  "expires": 1428360267,
  "capability": "{\"*\":[\"*\"]}"
}

Application routes

Routes providing access to the messaging service within an application scope.

Retrieve usage statistics for an application

GET rest.ably.io/stats

Example request:

curl https://rest.ably.io/stats?unit=hour \
 -u "xVLyHw.w4AJFg:w_yxn_fszUKE0JlY2Yo9Kwg4F0KsZcFWX7wa1WFm3qU"

The Ably system can be queried to obtain usage statistics for a given application, and results are provided aggregated across all channels in use in the application in the specified period. Stats may be used to track usage against account quotas.

Stats queries are made by specifying a query interval and the granularity expected in the results. The query interval is expressed as a start and end time, each being a timestamp in milliseconds since the epoch. Stats are aggregated by the system in ‘sub-minute’ intervals of 6s (ie 0.1m), so query interval start and end times are rounded down to the nearest sub-minute boundary.

Parameters
start
beginning of time The start of the query interval as a time in milliseconds since the epoch.
end
now The end of the query interval as a time in milliseconds since the epoch.
limit
100 The maximum number of records to return. A limit greater than 1,000 is invalid.
direction
backwards The direction of this query. The direction determines the order of the returned result array, but also determines which end of the query interval is the start point for the search.
unit
minute One of the values minute, hour, day or month, specifying the unit of aggregation in the returned results.
Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
yes (basic or token)
Returns

In each case a successful result is a paginated response with an array containing the items that match the query (and it may be empty).

Stats records contain a hierarchy of elements relating to messages, connections and other resources consumed in an interval. Any single record may contain a subset of the elements, omitting empty sections.

See a complete example of a statistics response.

Utilities

Get the service time

GET rest.ably.io/time

This returns the service time in milliseconds since the epoch. This may be used by clients that do not have local access to a sufficiently accurate time source when generating an Ably TokenRequest. (Ably TokenRequests include a timestamp and have a limited validity period to help defend against replay attacks.)

The result is a JSON-encoded array of length 1 containing the time result as a number.

curl http://rest.ably.io/time
Parameters

None

Options
Content-Type
not applicable
Accept
application/json by default, or application/x-msgpack, text/html
Auth required
no
Returns
[ _VAR_MS_SINCE_EPOCH_VAR_ ]

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.