Support messages API ref

Co-Authored-By: Kevin_Zheng <zhengzhenyu@huawei.com>
Co-Authored-By: Fei Long Wang <flwang@catalyst.net.nz>

Change-Id: If3fcb6594bc81736474875d5e1db0b465c6d750e

api-ref/source/index.rst

@@ -19,6 +19,7 @@ Messaging Service API v2 (CURRENT)
 
 .. include:: versions.inc
 .. include:: queues.inc
+.. include:: messages.inc
 .. include:: claims.inc
 .. include:: subscription.inc
 .. include:: health.inc

api-ref/source/messages.inc

@@ -0,0 +1,328 @@
+===================
+Messages (messages)
+===================
+
+Post Message
+============
+
+.. rest_method:: POST /v2/queues/{queue_name}/messages
+
+Posts the message or messages for the specified queue.
+
+This operation posts the specified message or messages.
+
+You can submit up to 10 messages in a single request, but you must always
+encapsulate the messages in a collection container (an array in JSON, even
+for a single message - without the JSON array, you receive the "Invalid request
+body" message). The resulting value of the Location header or response body
+might be used to retrieve the created messages for further processing.
+
+The client specifies only the body and TTL for the message. The server inserts
+metadata, such as ID and age.
+
+The response body contains a list of resource paths that correspond to each
+message submitted in the request, in the order of the messages. If a
+server-side error occurs during the processing of the submitted messages, a
+partial list is returned, the partial attribute is set to true, and the client
+tries to post the remaining messages again. If the server cannot enqueue any
+messages, the server returns a ``503 Service Unavailable`` error message.
+
+The ``body`` attribute specifies an arbitrary document that constitutes the
+body of the message being sent.
+
+.The following rules apply for the maximum size:
+
+The maximum size of posted messages is the maximum size of the entire request
+document (rather than the sum of the individual message body field values as
+it was in earlier releases). On error, the client will now be notified of how
+much it exceeded the limit.
+
+The size is limited to 256 KB, including whitespace.
+
+The document must be valid JSON. (The Message Queuing service validates it.)
+
+The ``ttl`` attribute specifies how long the server waits before marking the
+message as expired and removing it from the queue. The value of ``ttl`` must
+be between 60 and 1209600 seconds (14 days). Note that the server might not
+actually delete the message until its age has reached up to (ttl + 60) seconds,
+to allow for flexibility in storage implementations.
+
+
+Normal response codes: 201
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+
+Request Example
+---------------
+
+.. literalinclude:: samples/message-post-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - resources: messages_resources
+
+Response Example
+---------------
+
+.. literalinclude:: samples/message-post-response.json
+   :language: javascript
+
+
+List Messages
+=============
+
+.. rest_method:: GET /v2/queues/{queue_name}/messages
+
+List the messages in the specified queue.
+
+A request to list messages when the queue is not found or when messages are
+not found returns 204, instead of 200, because there was no information to
+send back. Messages with malformed IDs or messages that are not found by ID
+are ignored.
+
+This operation gets the message or messages in the specified queue.
+
+Message IDs and markers are opaque strings. Clients should make no assumptions
+about their format or length. Furthermore, clients should assume that there is
+no relationship between markers and message IDs (that is, one cannot be derived
+from the other). This allows for a wide variety of storage driver
+implementations.
+
+Results are ordered by age, oldest message first.
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - marker: marker
+  - limit: limit
+  - echo: echo
+  - include_claimed: include_claimed
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - messages: messages
+  - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/messages-list-response.json
+   :language: javascript
+
+
+Get A Set Of Messages By Id
+===========================
+
+.. rest_method:: GET /v2/queues/{queue_name}/messages?ids={ids}
+
+Gets a specified set of messages from the specified queue.
+
+This operation provides a more efficient way to query multiple messages
+compared to using a series of individual ``GET`` s. Note that the list of IDs
+cannot exceed 20. If a malformed ID or a nonexistent message ID is provided,
+it is ignored, and the remaining messages are returned.
+
+Unlike the Get Messages operation, a client's own messages are always returned
+in this operation. If you use the ids parameter, the echo parameter is not used
+and is ignored if it is specified.
+
+The message attributes are defined as follows: ``href`` is an opaque relative
+URI that the client can use to uniquely identify a message resource and
+interact with it. ``ttl`` is the TTL that was set on the message when it was
+posted. The message expires after (ttl - age) seconds. ``age`` is the number
+of seconds relative to the server's clock. ``body`` is the arbitrary document
+that was submitted with the original request to post the message.
+
+
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - ids: ids
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - messages: messages
+
+Response Example
+----------------
+
+.. literalinclude:: samples/messages-get-byids-response.json
+   :language: javascript
+
+
+Delete A Set Of Messages By Id
+==============================
+
+.. rest_method:: DELETE /v2/queues/{queue_name}/messages?ids={ids}
+
+Provides a bulk delete for messages.
+
+This operation immediately deletes the specified messages. If any of the
+message IDs are malformed or non-existent, they are ignored. The remaining
+valid messages IDs are deleted.
+
+
+
+Normal response codes: 204
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - ids: ids
+  - pop: pop
+
+
+This operation does not accept a request body and does not return a response
+body.
+
+
+Get A Specific Message
+======================
+
+.. rest_method:: GET /v2/queues/{queue_name}/messages/{messageId}
+
+Gets the specified message from the specified queue.
+
+This operation gets the specified message from the specified queue.
+
+If either the message ID is malformed or nonexistent, no message is returned.
+
+Message fields are defined as follows: ``href`` is an opaque relative URI that
+the client can use to uniquely identify a message resource and interact with
+it. ``ttl`` is the TTL that was set on the message when it was posted. The
+message expires after (ttl - age) seconds. ``age`` is the number of seconds
+relative to the server's clock. ``body`` is the arbitrary document that was
+submitted with the original request to post the message.
+
+
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - message_id: message_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/messages-get-response.json
+   :language: javascript
+
+
+Delete A Specific Message
+=========================
+
+.. rest_method:: DELETE /v2/queues/{queue_name}/messages/{messageId}
+
+Deletes the specified message from the specified queue.
+
+This operation immediately deletes the specified message.
+
+The ``claim_id`` parameter specifies that the message is deleted only if it
+has the specified claim ID and that claim has not expired. This specification
+is useful for ensuring only one worker processes any given message. When a
+worker's claim expires before it can delete a message that it has processed,
+the worker must roll back any actions it took based on that message because
+another worker can now claim and process the same message.
+
+If you do not specify ``claim_id``, but the message is claimed, the operation
+fails. You can only delete claimed messages by providing an appropriate
+``claim_id``.
+
+
+
+Normal response codes: 204
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - messageId: messageId
+
+This operation does not accept a request body and does not return a response
+body.
+

api-ref/source/parameters.yaml

@@ -4,7 +4,13 @@ client_id:
   type: UUID
   in: header
   description: |
-    A unique ID for indicating where the request come from.
+    A UUID for each client instance. The UUID must be submitted in its
+    canonical form (for example, 3381af92-2b9e-11e3-b191-71861300734c). The
+    client generates the Client-ID once. Client-ID persists between restarts
+    of the client so the client should reuse that same Client-ID. Note: All
+    message-related operations require the use of ``Client-ID`` in the headers
+    to ensure that messages are not echoed back to the client that posted
+    them, unless the client explicitly requests this.
 
 #### variables in path #######################################################
 
@@ -67,6 +73,42 @@ claim_limit:
     meaning the server may claim and return less than the requested number of
     messages.
 
+echo:
+   type: boolean
+   in: query
+   required: false
+   description:
+     Indicate if the messages can be echoed back to the client that posted
+     them.
+
+include_claimed:
+   type: boolean
+   in: query
+   required: false
+   description:
+     Indicate if the messages list should include the claimed messages.
+
+ids:
+  type: list
+  in: query
+  required: false
+  description: |
+    A list of the messages ids. ``pop`` & ``ids`` parameters are mutually
+    exclusive. Using them together in a request will result in HTTP 400.
+
+    NOTE: Actually, it's not a real list, it's string combined with many
+    message ids separated with comma, for example:
+    /messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f
+
+pop:
+  type: integer
+  in: query
+  required: false
+  description: |
+    The ``pop`` specifies how many messages will be popped up from the queue.
+    ``pop`` & ``ids`` parameters are mutually exclusive. Using them together
+    in a request will result in HTTP 400.
+
 #### variables in request ####################################################
 
 claim_ttl:
@@ -209,6 +251,19 @@ _default_message_ttl:
     one of the ``reserved attributes`` of Zaqar queues. The value will be
     reverted to the default value after deleting it explicitly.
 
+messages:
+  type: list
+  in: body
+  required: True
+  description: |
+    A list of the messages.
+
+messages_resources:
+  type: list
+  in: body
+  description: |
+    A list of the URL to messages.
+
 subscriptions:
   type: list
   in: body

api-ref/source/samples/messages-get-byids-response.json

@@ -0,0 +1,15 @@
+{
+    "messages": [
+        {
+            "body": {
+                "current_bytes": "0",
+                "event": "BackupProgress",
+                "total_bytes": "99614720"
+            },
+            "age": 443,
+            "href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
+            "id": "578f0055508f153f256f717f",
+            "ttl": 3600
+        }
+    ]
+}

api-ref/source/samples/messages-get-response.json

@@ -0,0 +1,11 @@
+{
+    "body": {
+        "current_bytes": "0",
+        "event": "BackupProgress",
+        "total_bytes": "99614720"
+    },
+    "age": 1110,
+    "href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
+    "id": "578f0055508f153f256f717f",
+    "ttl": 3600
+}

api-ref/source/samples/messages-list-response.json

@@ -0,0 +1,32 @@
+{
+    "messages": [
+        {
+            "body": {
+                "current_bytes": "0",
+                "event": "BackupProgress",
+                "total_bytes": "99614720"
+            },
+            "age": 482,
+            "href": "/v2/queues/beijing/messages/578edfe6508f153f256f717b",
+            "id": "578edfe6508f153f256f717b",
+            "ttl": 3600
+        },
+        {
+            "body": {
+                "current_bytes": "0",
+                "event": "BackupProgress",
+                "total_bytes": "99614720"
+            },
+            "age": 456,
+            "href": "/v2/queues/beijing/messages/578ee000508f153f256f717d",
+            "id": "578ee000508f153f256f717d",
+            "ttl": 3600
+        }
+    ],
+    "links": [
+        {
+            "href": "/v2/queues/beijing/messages?marker=17&echo=true",
+            "rel": "next"
+        }
+    ]
+}

api-ref/source/samples/messages-post-request.json

@@ -0,0 +1,18 @@
+{
+  "messages": [
+    {
+      "ttl": 300,
+      "body": {
+        "event": "BackupStarted",
+        "backup_id": "c378813c-3f0b-11e2-ad92-7823d2b0f3ce"
+      }
+    },
+    {
+      "body": {
+        "event": "BackupProgress",
+        "current_bytes": "0",
+        "total_bytes": "99614720"
+      }
+    }
+  ]
+}

api-ref/source/samples/messages-post-response.json

@@ -0,0 +1,6 @@
+{
+  "resources": [
+    "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357",
+    "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924358"
+  ]
+}