Rest api: add annotation docs

content/api/rest-api.textile

@@ -574,12 +574,107 @@ bc[json]. [{
 
 h3(#metadata-rest). Retrieve metadata for a channel
 
+h6. GET rest.ably.io/channels/@<channelId>@
+
 <%= partial partial_version('shared/_channel_metadata') %>
 
 h3(#enumeration-rest). Enumerate all active channels
 
+h6. GET rest.ably.io/channels
+
 <%= partial partial_version('shared/_channel_enumeration') %>
 
+h3(#annotations-publish). Publish annotations for a message
+
+h6. POST rest.ably.io/channels/@<channelId>@/messages/@<messageSerial>@/annotations
+
+Publish one or more annotations for a specific message identified by its serial in the @messageSerial@ url param. All annotations in a single request are published atomically and must be for the same message.
+
+See "our main annotation docs":/docs/messages/annotations for more information on annotations.
+
+The request body contains an array of annotation objects:
+
+bc[json]. [{
+  action: <number; 0 is create, 1 is delete>,
+  type: <string, specifies how this annotation should be aggregated>,
+  name: <optional string, arbitrary string that many aggregation types use to group by>,
+  count: <optional number, used with the 'multiple' aggregation type>,
+  id: <optional string, client-specified idempotency key>,
+  clientId: <optional string, explicit client identifier>,
+  data: <optional JSON-encodable data>,
+  encoding: <optional string, encoding if specifying manually>,
+  extras: <optional extras object>
+}]
+
+In JSON format, the accepted types for the @data@ payload are:
+
+* string
+* any JSON-encodable Array or Object.
+
+MessagePack additionally "supports byte arrays":https://github.com/msgpack/msgpack/blob/master/spec.md#formats-bin
+
+For annotation types and aggregation details, see "annotation types":/docs/messages/annotations#annotation-types.
+
+The message extras object is the same as for a message publish, see "message extras":/docs/api/rest-api#message-extras.
+
+The id is the same as for a message publish, see "idempotent publishing":/docs/api/rest-api#idempotent-publish
+
+Example request:
+
+bc[sh]. curl -X POST https://rest.ably.io/channels/mutable:channel/messages/01726585978590-001@abcdefghij:001/annotations \
+ -u "{{API_KEY}}" \
+ -H "Content-Type: application/json" \
+ --data '[{ "action": 0, "type": "reaction:distinct.v1", "name": ":thumbsup:" }]'
+
+h5. Options
+
+- Content-Type := @application/json@ or @application/x-msgpack@
+- Accept := @application/json@ (the default), @application/x-msgpack@
+- Auth required := yes ("basic":#basic-authentication or "token":#token-authentication)
+
+h5. Returns
+
+When successful, returns status code 201 and an object with annotation details. When unsuccessful, returns an error as an "ErrorInfo":/docs/api/rest-sdk/types#error-info object.
+
+h3(#annotations-list). Retrieve all annotations for a message
+
+h6. GET rest.ably.io/channels/@<channelId>@/messages/@<messageSerial>@/annotations
+
+Retrieve all annotations that have been published for a specific message identified by its serial, starting from the earliest.
+
+Example request:
+
+bc[sh]. curl https://rest.ably.io/channels/rest-example/messages/01726585978590-001@abcdefghij:001/annotations?limit=100 \
+ -u "{{API_KEY}}"
+
+h5. Parameters
+
+- limit := _100_ The maximum number of records to return per page. A limit greater than 1,000 is invalid.
+
+h5. Options
+
+- Accept := @application/json@ by default, or @application/x-msgpack@
+- Auth required := yes ("basic":#basic-authentication or "token":#token-authentication)
+
+h5. Returns
+
+A successful request returns a "paginated response":#pagination with an array containing the annotations for the specified message, starting from the first one to have been published for that message. If there are no annotations, an empty collection is returned.
+
+bc[json]. [{
+  action: <number; 0 for create, 1 for delete>,
+  serial: <unique serial of this annotation>,
+  id: <idempotency key>,
+  timestamp: <annotation timestamp in ms since epoch>
+  messageSerial: <the serial of the message that is being annotated>
+  type: <annotation type>,
+  name: <optional string>,
+  count: <optional number>,
+  clientId: <optional client identifier>,
+  data: <optional annotation payload>,
+  encoding: <optional encoding of the payload>,
+  extras: <optional extras object>,
+}]
+
 h2(#push). Push
 
 h3(#post-device-registration). Register a device for receiving push notifications