Add Claims for api ref

Change-Id: Id9ac39f69b3e042f61ee9ae6d2abbca36c7a4e34

api-ref/source/claims.inc

@@ -0,0 +1,216 @@
+===============
+Claims (claims)
+===============
+
+Claim messages
+==============
+
+.. rest_method:: POST /v2//queues/{queue_name}/claims
+
+Claims a set of messages from the specified queue.
+
+This operation claims a set of messages (up to the value of the ``limit``
+parameter) from oldest to newest and skips any messages that are already
+claimed. If no unclaimed messages are available, the API returns a
+``204 No Content`` message.
+
+When a client (worker) finishes processing a message, it should delete the
+message before the claim expires to ensure that the message is processed only
+once. As part of the delete operation, workers should specify the claim ID
+(which is best done by simply using the provided href). If workers perform
+these actions, then if a claim simply expires, the server can return an error
+and notify the worker of the race condition. This action gives the worker a
+chance to roll back its own processing of the given message because another
+worker can claim the message and process it.
+
+The age given for a claim is relative to the server's clock. The claim's age
+is useful for determining how quickly messages are getting processed and
+whether a given message's claim is about to expire.
+
+When a claim expires, it is released. If the original worker failed to process
+the message, another client worker can then claim the message.
+
+Note that claim creation is best-effort, meaning the worker may claim and
+return less than the requested number of messages.
+
+The ``ttl`` attribute specifies how long the server waits before releasing
+the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+You must include a value for this attribute in your request.
+
+The ``grace`` attribute specifies the message grace period in seconds. The
+value of ``grace`` value must be between 60 and 43200 seconds (12 hours).
+You must include a value for this attribute in your request. To deal with
+workers that have stopped responding (for up to 1209600 seconds or 14 days,
+including claim lifetime), the server extends the lifetime of claimed messages
+to be at least as long as the lifetime of the claim itself, plus the specified
+grace period. If a claimed message would normally live longer than the grace
+period, its expiration is not adjusted.
+
+
+
+Normal response codes: 201
+
+Error response codes:
+
+- Unauthorized(401)
+- Forbidden(403)
+- itemNotFound(404)
+- ServiceUnavailable(503)
+
+Request Parameters
+------------------
+
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - limit: claim_limit
+  - ttl: claim_ttl
+  - grace: claim_grace
+
+**Example Claim Messages: JSON request**
+
+
+.. literalinclude:: samples/claim_messages_request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+**Example Claim Messages: JSON response**
+
+
+.. literalinclude:: samples/claim_messages_response.json
+   :language: javascript
+
+
+
+Query Claim
+===========
+
+.. rest_method:: GET /v2/queues/{queue_name}/claims/{claim_id}
+
+Queries the specified claim for the specified queue.
+
+This operation queries the specified claim for the specified queue. Claims
+with malformed IDs or claims that are not found by ID are ignored.
+
+
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized(401)
+- Forbidden(403)
+- itemNotFound(404)
+- ServiceUnavailable(503)
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - claim_id: claim_id
+
+Response Parameters
+-------------------
+
+**Example Query Claim: JSON response**
+
+
+.. literalinclude:: samples/claim_query_response.json
+   :language: javascript
+
+
+
+Update(Renew) Claim
+===================
+
+.. rest_method:: PATCH /v2/queues/{queue_name}/claims/{claim_id}
+
+Updates the specified claim for the specified queue.
+
+This operation updates the specified claim for the specified queue. Claims
+with malformed IDs or claims that are not found by ID are ignored.
+
+Clients should periodically renew claims during long-running batches of work
+to avoid losing a claim while processing a message. The client can renew a
+claim by issuing a ``PATCH`` command to a specific claim resource and
+including a new TTL for the claim (which can be different from the original
+TTL). The server resets the age of the claim and applies the new TTL.
+
+
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized(401)
+- Forbidden(403)
+- itemNotFound(404)
+- ServiceUnavailable(503)
+
+Request Parameters
+------------------
+
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - claim_id: claim_id
+  - ttl: claim_ttl
+  - grace: claim_grace
+
+**Example Update Claim: JSON request**
+
+
+.. literalinclude:: samples/claim_update_request.json
+   :language: javascript
+
+
+This operation does not return a response body.
+
+
+Delete(Release) Claim
+=====================
+
+.. rest_method:: DELETE /v2/queues/{queue_name}/claims/{claim_id}
+
+Releases the specified claim for the specified queue.
+
+This operation immediately releases a claim, making any remaining, undeleted)
+messages that are associated with the claim available to other workers. Claims
+with malformed IDs or claims that are not found by ID are ignored.
+
+This operation is useful when a worker is performing a graceful shutdown,
+fails to process one or more messages, or is taking longer than expected to
+process messages, and wants to make the remainder of the messages available
+to other workers.
+
+
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized(401)
+- Forbidden(403)
+- itemNotFound(404)
+- ServiceUnavailable(503)
+
+Request Parameters
+------------------
+
+
+.. rest_parameters:: parameters.yaml
+
+  - queue_name: queue_name
+  - claim_id: claim_id
+
+
+This operation does not accept a request body and does not return a response
+body.

api-ref/source/index.rst

@@ -19,3 +19,4 @@ Messaging Service API v2 (CURRENT)
 
 .. include:: versions.inc
 .. include:: queues.inc
+.. include:: claims.inc

api-ref/source/parameters.yaml

@@ -15,6 +15,13 @@ queue_name:
   description: |
     The name of the queue.
 
+claim_id:
+  type: string
+  in: path
+  required: True
+  description: |
+    The id of the claim.
+
 #### variables in query ######################################################
 
 limit:
@@ -36,6 +43,41 @@ marker:
     initial limited request and use the ID of the last-seen item from the
     response as the ``marker`` parameter value in a subsequent limited request.
 
+claim_limit:
+  type: integer
+  in: query
+  required: false
+  description: |
+    The ``limit`` specifies up to 20 messages (configurable) to claim. If not
+    specified, limit defaults to 10. Note that claim creation is best-effort,
+    meaning the server may claim and return less than the requested number of
+    messages.
+
+#### variables in request ####################################################
+
+claim_ttl:
+  type: integer
+  in: body
+  required: false
+  description: |
+    The ``ttl`` attribute specifies how long the server waits before releasing
+    the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+    You must include a value for this attribute in your request.
+
+claim_grace:
+  type: integer
+  in: body
+  required: false
+  description: |
+    The ``grace`` attribute specifies the message grace period in seconds. The
+    value of ``grace`` value must be between 60 and 43200 seconds (12 hours).
+    You must include a value for this attribute in your request. To deal with
+    workers that have stopped responding (for up to 1209600 seconds or 14 days,
+    including claim lifetime), the server extends the lifetime of claimed
+    messages to be at least as long as the lifetime of the claim itself, plus
+    the specified grace period. If a claimed message would normally live longer
+    than the grace period, its expiration is not adjusted.
+
 #### variables in response ###################################################
 
 versions:

api-ref/source/samples/claim_messages_request.json

@@ -0,0 +1,4 @@
+{
+    "ttl": 300,
+    "grace": 300
+}

api-ref/source/samples/claim_messages_response.json

@@ -0,0 +1,10 @@
+[
+  {
+    "body": {
+      "event": "BackupStarted"
+    },
+    "age": 239,
+    "href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
+    "ttl": 300
+  }
+]

api-ref/source/samples/claim_query_response.json

@@ -0,0 +1,15 @@
+{
+  "age": 57,
+  "href": "/v2/queues/demoqueue/claims/51db7067821e727dc24df754",
+  "messages": [
+    {
+      "body": {
+        "event": "BackupStarted"
+      },
+      "age": 296,
+      "href": "/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754",
+      "ttl": 300
+    }
+  ],
+  "ttl": 300
+}

api-ref/source/samples/claim_update_request.json

@@ -0,0 +1,4 @@
+{
+  "ttl": 300,
+  "grace": 300
+}