Merge pull request #2886 from ably/EDU-2046-Convert-Pub-Sub-channel-metadata-API-refs-to-MDX

Migrate Realtime SDK API spec channel-metadata page to MDX

Author: GregHolmes

content/api/realtime-sdk/channel-metadata.textile

@@ -0,0 +1,74 @@
+---
+title: Channel Metadata
+meta_description: "Realtime Client Library SDK API reference section for channel metadata."
+meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, metadata, channel metadata, occupancy"
+redirect_from:
+  - /docs/api/versions/v1.1/realtime-sdk/channel-metadata
+  - /docs/api/versions/v1.0/realtime-sdk/channel-metadata
+---
+
+## Types <a id="types" />
+
+The payload of metadata events for channels is the [`ChannelDetails`](#channel-details) type which contains the `channelId` and other static information about the channel, plus a `status` containing a [`ChannelStatus`](#channel-status) instance which contains information about the current state of the channel.
+
+### ChannelDetails <a id="channel-details" />
+
+`ChannelDetails` is an object returned when requesting or receiving [channel metadata](/docs/metadata-stats/metadata). It contains information on the channel itself, along with the current state of the channel in the [ChannelStatus](#channel-status) object.
+
+| Name | Description | Type |
+|------|-------------|------|
+| channelId | the required name of the channel including any qualifier, if any | `string` |
+| region | in events relating to the activity of a channel in a specific region, this optionally identifies the region | `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 | `boolean` |
+| status | an optional [`ChannelStatus`](#channel-status) instance | [`ChannelStatus`](#channel-status) |
+
+The following is an example of a `ChannelDetails` JSON object:
+
+<Code>
+```json
+{
+  "channelId": "foo",
+  "status": {
+    "isActive": true,
+    "occupancy": {
+      "metrics": {
+        "connections": 1,
+        "publishers": 1,
+        "subscribers": 1,
+        "presenceConnections": 1,
+        "presenceMembers": 0,
+        "presenceSubscribers": 1,
+        "objectPublishers": 1,
+        "objectSubscribers": 1
+      }
+    }
+  }
+}
+```
+</Code>
+
+### ChannelDetails.ChannelStatus <a id="channel-status" />
+
+`ChannelStatus` is contained within the [`ChannelDetails`](#channel-details) object, and optionally contains an [Occupancy](#occupancy) object.
+
+| Name | Description | Type |
+|------|-------------|------|
+| 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 | `boolean` |
+| occupancy | an optional [`Occupancy`](#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. | [`Occupancy`](#occupancy) |
+
+### ChannelDetails.ChannelStatus.Occupancy <a id="occupancy" />
+
+Occupancy is optionally contained within the [`ChannelStatus`](#channel-status) object, and contains metadata relating to the occupants of the channel. This is usually contained within the `occupancy` attribute of the [`ChannelStatus`](#channel-status) object.
+
+The `occupancy` attribute contains the `metrics` attribute, which contains the following members:
+
+| Name | Description | Type |
+|------|-------------|------|
+| connections | the number of connections | `integer` |
+| publishers | the number of connections attached to the channel that are authorised to publish | `integer` |
+| subscribers | the number of connections attached that are authorised to subscribe to messages | `integer` |
+| presenceSubscribers | the number of connections that are authorised to subscribe to presence messages | `integer` |
+| presenceConnections | the number of connections that are authorised to enter members into the presence channel | `integer` |
+| presenceMembers | the number of members currently entered into the presence channel | `integer` |
+| objectPublishers | the number of connections that are authorised to publish updates to objects on the channel | `integer` |
+| objectSubscribers | the number of connections that are authorised to subscribe to objects on the channel | `integer` |