Add docs for message updates and deletes

content/api/realtime-sdk/types.textile

@@ -81,11 +81,12 @@ h3(#message).
 
 <%= partial partial_version('types/_message') %>
 
-blang[jsall].
-  h3(#message-action).
-    default: Message action
+h3(#message-action).
+  default: MessageAction
+  objc,swift: ARTMessageAction
+  java:    io.ably.lib.types.Message.Action
 
-  <%= partial partial_version('types/_message_action') %>
+<%= partial partial_version('types/_message_action') %>
 
 h3(#message-annotations).
   default: MessageAnnotations

content/api/rest-api.textile

@@ -14,6 +14,10 @@ jump_to:
   Channel API:
     - publish
     - message history#message-history
+    - get message#get-message
+    - update message#update-message
+    - delete message#delete-message
+    - message versions#message-versions
     - presence
     - presence history
   Push API:
@@ -499,6 +503,227 @@ bc[json]. [{
   timestamp: <message timestamp in ms since epoch>
 }]
 
+h3(#get-message). Get latest version of a message
+
+h6. GET main.realtime.ably.net/channels/@<channelId>@/messages/@<serial>@
+
+Retrieve the latest version of a specific message by its serial identifier.
+
+Example request:
+
+bc[sh]. curl https://main.realtime.ably.net/channels/rest-example/messages/01826232498871-001@abcdefghij:001 \
+ -u "{{API_KEY}}"
+
+
+h5. Options
+
+- Accept := @application/json@ or @application/x-msgpack@
+- Auth required := yes ("basic":#basic-authentication or "token":#token-authentication with @history@ capability)
+
+h5. Returns
+
+A successful request returns a single @Message@ object containing the latest version of the message.
+
+See "MessageAction":/docs/api/realtime-sdk/types#message-action for the possible values of the @action@ enum.
+
+bc[json]. {
+  serial: <permanent message serial identifier>,
+  name: <event name>,
+  data: <message payload>,
+  timestamp: <original message timestamp in ms since epoch>,
+  clientId: <client id of original publisher>,
+  action: <MessageAction int enum>,
+  version: {
+    serial: <version serial identifier>,
+    clientId: <client id of user who made the latest update>,
+    timestamp: <version timestamp in ms since epoch>,
+    description: <optional description of the operation>,
+    metadata: <optional metadata object>
+  }
+}
+
+An unsuccessful request returns an error. A 404 error is returned if a message with that serial does not exist.
+
+h3(#update-message). Update a message
+
+h6. PATCH main.realtime.ably.net/channels/@<channelId>@/messages/@<serial>@
+
+Update an existing message on a channel, the message with the specified serial. This endpoint requires that the channel is configured with the "Message annotations, updates, and deletes" channel rule.
+
+See "Updating and deleting messages":/docs/messages/updates-deletes#update for more information about message updates and field semantics.
+
+The request body contains the message fields to update, along with optional operation metadata. Any fields not specified will be left as their original values.
+
+bc[json]. {
+  name: <optional new event name>,
+  data: <optional new message payload>,
+  encoding: <optional encoding if data was encoded>,
+  extras: <optional new extras field>,
+  operation: {
+    clientId: <optional, client id performing the update>,
+    description: <optional description of why the update was made>,
+    metadata: <optional metadata object>
+  }
+}
+
+Example request:
+
+bc[sh]. curl -X PATCH https://main.realtime.ably.net/channels/rest-example/messages/01826232498871-001@abcdefghij:001 \
+ -u "{{API_KEY}}" \
+ -H "Content-Type: application/json" \
+ --data \
+ '{
+   "data": "updated message content",
+   "operation": {
+     "description": "Fixed typo"
+   }
+ }'
+
+h5. Options
+
+- Content-Type := @application/json@, @application/x-msgpack@ or @application/x-www-form-urlencoded@
+- Accept := @application/json@ by default or @application/x-msgpack@
+- Auth required := yes ("basic":#basic-authentication or "token":#token-authentication with @message-update-own@ or @message-update-any@ capability)
+
+h5. Capabilities
+
+- @message-update-own@ := Can update your own messages (messages where the original publisher's @clientId@ matches the updater's @clientId@, where both are "identified":/docs/auth/identified-clients)
+- @message-update-any@ := Can update any message on the channel
+
+h5. Returns
+
+A successful request returns the updated @Message@ object with the new version information.
+
+See "MessageAction":/docs/api/realtime-sdk/types#message-action for the possible values of the @action@ enum.
+
+bc[json]. {
+  serial: <permanent message serial identifier>,
+  name: <event name>,
+  data: <updated message payload>,
+  timestamp: <original message timestamp in ms since epoch>,
+  clientId: <client id of original publisher>,
+  action: <MessageAction int enum>,
+  version: {
+    serial: <new version serial identifier>,
+    clientId: <client id of user who made the update>,
+    timestamp: <update timestamp in ms since epoch>,
+    description: <description of the operation if provided>,
+    metadata: <metadata object if provided>
+  }
+}
+
+An unsuccessful request returns an error.
+
+h3(#delete-message). Delete a message
+
+h6. POST main.realtime.ably.net/channels/@<channelId>@/messages/@<serial>@/delete
+
+Delete a message on a channel, the message with the specified serial. This is a 'soft' delete that publishes a new version of the message with an action of @message.delete@. The full message history remains accessible through the "message versions":#message-versions endpoint. This endpoint requires that the channel is configured with the "Message annotations, updates, and deletes" channel rule.
+
+See "Updating and deleting messages":/docs/messages/updates-deletes#update for more information about message updates and field semantics.
+
+The request body contains the message fields to update, along with optional operation metadata. Any fields not specified will be left as their original values.
+
+bc[json]. {
+  name: <optional new event name for the deleted version>,
+  data: <optional new data for the deleted version>,
+  encoding: <optional encoding if data was encoded>,
+  extras: <optional new extras field>,
+  operation: {
+    clientId: <optional, client id performing the delete>,
+    description: <optional description of why the delete was made>,
+    metadata: <optional metadata object>
+  }
+}
+
+Example request:
+
+bc[sh]. curl -X POST https://main.realtime.ably.net/channels/rest-example/messages/01826232498871-001@abcdefghij:001/delete \
+ -u "{{API_KEY}}" \
+ -H "Content-Type: application/json" \
+ --data \
+ '{
+   "operation": {
+     "description": "Content violation"
+   }
+ }'
+
+h5. 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":#basic-authentication or "token":#token-authentication with @message-delete-own@ or @message-delete-any@ capability)
+
+h5. Capabilities
+
+- @message-delete-own@ := Can delete your own messages (messages where the original publisher's @clientId@ matches the deleter's @clientId@, where both are "identified":/docs/auth/identified-clients)
+- @message-delete-any@ := Can delete any message on the channel
+
+h5. Returns
+
+A successful request returns the updated @Message@ object with @action@ set to @message.delete@.
+
+See "MessageAction":/docs/api/realtime-sdk/types#message-action for the possible values of the @action@ enum.
+
+bc[json]. {
+  serial: <permanent message serial identifier>,
+  name: <event name if provided>,
+  data: <data if provided>,
+  timestamp: <original message timestamp in ms since epoch>,
+  clientId: <client id of original publisher>,
+  action: <MessageAction int enum>,
+  version: {
+    serial: <new version serial identifier>,
+    clientId: <client id of user who made the delete>,
+    timestamp: <delete timestamp in ms since epoch>,
+    description: <description of the operation if provided>,
+    metadata: <metadata object if provided>
+  }
+}
+
+An unsuccessful request returns an error.
+
+h3(#message-versions). Retrieve message version history
+
+h6. GET main.realtime.ably.net/channels/@<channelId>@/messages/@<serial>@/versions
+
+Retrieve all historical versions of a specific message, including the original and all subsequent updates or delete operations. This endpoint requires that the channel is configured with the "Message annotations, updates, and deletes" channel rule.
+
+Example request:
+
+bc[sh]. curl https://main.realtime.ably.net/channels/rest-example/messages/01826232498871-001@abcdefghij:001/versions \
+ -u "{{API_KEY}}"
+
+h5. Options
+
+- Content-Type := not applicable
+- Accept := @application/json@ by default, or @application/x-msgpack@, @text/html@
+- Auth required := yes ("basic":#basic-authentication or "token":#token-authentication with @history@ capability)
+
+h5. Returns
+
+A successful request returns a "paginated response":#pagination containing all versions of the message, ordered by version serial (oldest to newest).
+
+See "MessageAction":/docs/api/realtime-sdk/types#message-action for the possible values of the @action@ enum.
+
+bc[json]. [{
+  serial: <permanent message serial identifier>,
+  name: <event name>,
+  data: <message payload>,
+  timestamp: <original message timestamp in ms since epoch>,
+  clientId: <client id of original publisher>,
+  action: <MessageAction int enum>,
+  version: {
+    serial: <version serial identifier>,
+    clientId: <client id of user who created this version>,
+    timestamp: <version timestamp in ms since epoch>,
+    description: <optional description if provided>,
+    metadata: <optional metadata if provided>
+  }
+}]
+
+An unsuccessful request returns an error.
+
 h3(#presence). Retrieve instantaneous presence status for a channel
 
 h6. GET main.realtime.ably.net/channels/@<channelId>@/presence
@@ -525,13 +750,16 @@ h5. Options
 h5. Returns
 
 A successful request returns a "paginated response":#pagination 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.
+<presence state>,
+
+See "PresenceAction":/docs/api/realtime-sdk/types#presence-action for the possible values of the @action@ enum.
 
 bc[json]. [{
   id: <a unique member identifier 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>,
+  action: <PresenceAction int enum>
   data: <optional clientData provided by the client>
 }]
 
@@ -563,12 +791,14 @@ h5. Returns
 
 A successful request returns a "paginated response":#pagination 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.
 
+See "PresenceAction":/docs/api/realtime-sdk/types#presence-action for the possible values of the @action@ enum.
+
 bc[json]. [{
   id: <a unique member identifier 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>,
+  action: <PresenceAction int enum>
   data: <optional clientData provided by the client>
 }]
 
@@ -1476,10 +1706,12 @@ bc[text]. [{
   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>,
+  action: <PresenceAction int enum>
   data: <optional clientData provided by the client>
 }]
 
+See "PresenceAction":/docs/api/realtime-sdk/types#presence-action for the possible values of the @action@ enum.
+
 *Failure*: If the batch request itself fails the response body contains an "ErrorInfo":/docs/api/rest-sdk/types#error-info object.
 
 *Partial success*: If the batch request itself succeeds, but one or more of the requests within the batch fails, then the response for the failed request contains an error object with the error code @40020@ and a status code of @400@. Successful requests within the batch include a @presence@ array that describes the presence state of each of the channel members.