REST Client Library API

Channel Status API

Overview

The Channel Status API provides the capability to access information about channels via the Ably REST endpoint. The information includes the current state of a channel, or its current occupancy. This data can be accessed as follows:

At present, REST requests for lifecycle events do not count towards your message limit. If you are making use of Reactor however, then each message sent over Reactor will count towards your message limits.

Note that it is also possible to use the realtime endpoint to subscribe to:

  • Metachannels – to obtain channel and connection lifecycle metadata.
  • Inband channel occupancy events – to obtain occupancy metrics such as the counts of publishers, subscribers or presence members as they are added or removed.

Note that since the metadata of various channels is prone to change very frequently, unless you have a special use case within your app, Ably recommends you subscribe to the realtime events using metchannels or inband channel occupancy rather than polling for status updates via REST, as this is inefficient and data is likely to become stale as soon as you have received it.

Requesting Channel Status

Through the REST library, it is possible to not only check a channel’s status and occupancy data, but it is also possible to enumerate all channels that are currently active within an app.

Channel lifecycle status

This returns a ChannelDetails for the given channel, indicating global occupancy. A side-effect of this request, in the current version 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.

Example request:

curl https://rest.ably.io/channels/<channelId> \
 -u "xVLyHw.0dczBw:v3jpxjl4B-AfQUP-"

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.

Channel enumeration

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.

This API is intended for occasional use by your servers only; for example, to get an initial set of active channels to be kept up to date using the channel lifecycle metachannel . It is heavily rate-limited: only a single in-flight channel enumeration call is permitted to execute at any one time. Further concurrent calls will be refused with an error with code 42912.

Example request:

curl https://rest.ably.io/channels \
 -u "xVLyHw.0dczBw:v3jpxjl4B-AfQUP-"

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 is the default, but if you do not actually need the extra information you get with that, we strongly recommend you use by=id, which will be faster)

The credentials presented with the request must include the channel-metadata permission for the wildcard resource '*'.

Client libraries 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, this is subject to several 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 continuously inactive between those times then it is guaranteed not to be present in the result;
  • Since the state of the cluster may change between successive calls, a pagination sequence may 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 maybe provided in later versions of this API. Enumerations that are satisfiable in the first response page do not have this issue.
  • The API does not guarantee that the limit will be achieved even if that would be possible. For example, if you specify a limit of 100, the API may return only 37 results together with a next link to get the next page, even if you have more than 37 channels. In the extreme case, the API may return 0 results with a next link. In particular this may be the case if you have a large number of active channels but are specifing a prefix that excludes a significant proportion of them.
  • The API does not guarantee that there will be no duplicated results between different pages, especially if a channel is alive in multiple regions. (It does not currently do so, but it may begin to do so with no warning or deprecation period, so your implementation should be able to cope with duplication)

Tutorials

Tutorials provide step-by-step documentation on how to obtain and use metadata:

Channel Status API Reference

Types

The payload of metadata events for channels is the ChannelDetails type which contains the channelId (AKA the channel’s name) and other static information about the channel, plus a status containing a ChannelStatus instance which contains information about the current state of the channel.

ChannelDetails

ChannelDetails is an object returned when requesting or receiving channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.

channelId
the required name of the channel including any qualifier, if any
Type: string
region
in events relating to the activity of a channel in a specific region, this optionally identifies the region
Type: string
isGlobalMaster
in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel
Type: boolean
status
an optional ChannelStatus instance
Type: ChannelStatus
{
  "channelId": "foo",
  "status": {
    "isActive": true,
    "occupancy": {
      "metrics": {
        "connections": 1,
        "publishers": 1,
        "subscribers": 1,
        "presenceConnections": 1,
        "presenceMembers": 0,
        "presenceSubscribers": 1
      }
    }
  }
}

ChannelDetails.ChannelStatus

ChannelStatus is contained within the ChannelDetails object, and optionally contains an Occupancy object.

isActive
a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity
Type: boolean
occupancy
an optional Occupancy instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
Type: Occupancy

ChannelDetails.ChannelStatus.Occupancy

Occupancy is optionally contained within the ChannelStatus object, and contains metadata relating to the occupants of the channel. This is usually contained within the occupancy attribute of the ChannelStatus object.

The occupancy attribute contains the metrics attribute, which contains the following members:

connections
the number of connections
Type: integer
publishers
the number of connections attached to the channel that are authorised to publish
Type: integer
subscribers
the number of connections attached that are authorised to subscribe to messages
Type: integer
presenceSubscribers
the number of connections that are authorised to subscribe to presence messages
Type: integer
presenceConnections
the number of connections that are authorised to enter members into the presence channel
Type: integer
presenceMembers
the number of members currently entered into the presence channel
Type: integer

API reference
Documentation