zaqar/doc/source/headers_queue_api_working.rst

Common Headers
==============

Each request to the Message Queuing API must include certain standard
and extended HTTP headers (as shown in the following table). These
headers provide host, agent, authentication, and other pertinent
information to the server. The following table provides the common
headers used by the API.

.. list-table::
   :widths: 50 50
   :header-rows: 1

   * - Header
     - Description
   * - Host
     - Host name of the API
   * - Date
     - Current date and time
   * - Accept
     - Media type to use. Initially, only ``application/json`` is
       supported. **Note: The "Accept" header is required.**
   * - Accept-Encoding
     - Specifies that the agent accepts gzip-encoded response bodies
   * - Content-Type
     - ``application/json``
   * - Content-Length
     - For ``POST`` or ``PUT`` requests, the length in bytes of the
       message document being submitted
   * - X-Auth-Token
     - Authorization token
   * - X-Project-Id
     - An ID for a project to which the value of X-Auth-Token grants
       access. Queues are created under this project. The project ID
       is the same as the account ID (also sometimes called tenant ID).
   * - Client-ID
     - 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.**

Working with the Message Queuing API
====================================

This chapter contains a simple exercise with some basic Message Queuing
requests that you will commonly use. Example requests are provided in
cURL, followed by the response.

For a complete list of operations available for Message Queuing, see :doc:`getting_started`
Each operation is fully described in the `Message Queuing API v2
Reference <http://developer.openstack.org/api-ref/messaging>`_.

Create Queue
------------

The Create Queue operation creates a queue in the region of your choice.

The body of the PUT request is empty.

The template is as follows:

.. code:: json

    PUT {endpoint}/queues/{queue_name}

The ``queue_name`` parameter specifies the name to give the queue. The
name *must not* exceed 64 bytes in length and is limited to US-ASCII
letters, digits, underscores, and hyphens.

Following are examples of a Create Queue request and response:

.. code-block:: bash

    curl -i -X PUT https://queues.api.openstack.org/v2/queues/samplequeue \
    -H "X-Auth-Token: " \
    -H "Accept: application/json" \
    -H "X-Project-Id: "

.. code:: json

    HTTP/1.1 201 Created
    Content-Length: 0
    Location: /v2/queues/samplequeue

Post Message
------------

The Post Message operation inserts one or more messages in a queue.

You can submit up to 10 messages in a single request, but you must
encapsulate them in a collection container (an array in JSON, even for a
single message - without the JSON array, you receive an "Invalid body
request" error message). You can use the resulting value of the location
header or response body to retrieve the created messages for further
processing if needed.

The template is as follows:

.. code:: json

    POST {endpoint}/queues/{queue_name}/messages

The client specifies only the body and ttl attributes for the message.
Metadata, such as id and age, is added.

The response body contains a list of resource paths that correspond to
each message submitted in the request, in the same order as they were
submitted.

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.

    **Important**

    The ``partial`` attribute has been deprecated in the v1.0 API and is
    not available in the v1.1 API. Drivers are now required to operate
    in a transactional manner. In other words, either all messages must
    be posted, or none of them.

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 size is limited to 256 KB for the entire request body (as-is),
   including whitespace.

-  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 earlier releases). On error, the
   client is notified of by how much the request exceeded the limit.

The document *must* be valid JSON. (The Message Queuing service
validates it.)

The ``ttl`` attribute specifies the lifetime of the message. When the
lifetime expires, the server deletes the message and removes it from the
queue. Valid values are 60 through 1209600 seconds (14 days).

    **Note**

    The server might not actually delete the message until its age
    reaches (ttl + 60) seconds. So there might be a delay of 60 seconds
    after the message expires before it is deleted.

The following are examples of a Post Message request and response:

.. code:: bash

    curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/messages -d \
    '[{"ttl": 300,"body": {"event": "BackupStarted"}},{"ttl": 60,"body": {"play": "hockey"}}]' \
    -H "Content-type: application/json" \
    -H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
    -H "X-Auth-Token: " \
    -H "Accept: application/json" \
    -H "X-Project-Id: "

.. code:: json

    HTTP/1.1 201 Created
    Content-Length: 153
    Content-Type: application/json; charset=utf-8
    Location: /v1/queues/samplequeue/messages?ids=51ca00a0c508f154c912b85c,51ca00a0c508f154c912b85d

    {"partial": false, "resources": ["/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c", "/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85d"]}

Claim Messages
--------------

The Claim Messages 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 there are no messages available to claim,
the Message Queuing service returns an HTTP ``204 No Content`` response
code.

The template is as follows:

.. code:: json

    POST {endpoint}/queues/{queue_name}/claims{?limit}
    Content-Type: application/json

    {
        "ttl": {claim_ttl},
        "grace": {message_grace}
    }

The client (worker) needs to delete the message when it has finished
processing it. The client deletes the message before the claim expires
to ensure that the message is processed only once. If a client needs
more time, the Cloud Service provides the Update Claim operation to make
changes. See the Message Queuing API v1 Reference for a description of
this operation. As part of the delete operation, workers 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 a possible 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 back to the queue for other workers
to claim. (If the original worker failed to process the message, another
client worker can then claim the message.)

The ``limit`` parameter specifies the number of messages to claim. The
``limit`` parameter is configurable. The default is 20. Messages are
claimed based on the number of messages available. The server might
claim and return less than the requested number of messages.

The ``ttl`` attribute specifies the lifetime of the claim. While
messages are claimed, they are not available to other workers. The value
must be between 60 and 43200 seconds (12 hours).

The ``grace`` attribute specifies the message grace period in seconds.
Valid values are between 60 and 43200 seconds (12 hours). 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 normally
lives longer than the grace period, its expiration is not adjusted. it

Following are examples of a Claim Messages request and response:

.. code:: bash

    curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/claims -d \
    '{"ttl": 300,"grace":300}' \
    -H "Content-type: application/json" \
    -H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
    -H "X-Auth-Token: " \
    -H "Accept: application/json" \
    -H "X-Project-Id: "

.. code:: http

    HTTP/1.1 201 OK
    Content-Length: 164
    Content-Type: application/json; charset=utf-8
    Location: /v1/queues/samplequeue/claims/51ca011c821e7250f344efd6
    X-Project-Id:

    [
      {
        "body": {
          "event": "BackupStarted"
        },
        "age": 124,
        "href": "\/v1\/queues\/samplequeue\/messages\/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6",
        "ttl": 300
      }
    ]

Delete Message with Claim ID
----------------------------

The Delete Message operations deletes messages.

The template is as follows:

.. code:: http

    DELETE {endpoint}/queues/{queue_name}/messages/{message_id}{?claim_id}

The ``message_id`` parameter specifies the message to delete.

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 that only one worker processes any
given message. When a worker's claim expires before it deletes 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.

Following are examples of a Delete Message request and response:

.. code:: bash

    curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6 \
    -H "Content-type: application/json" \
    -H "X-Auth-Token: " \
    -H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
    -H "Accept: application/json" \
    -H "X-Project-Id: "

.. code:: http

    HTTP/1.1 204 No Content

Release Claim
-------------

The Release Claim operation immediately releases a claim, making any
remaining, undeleted) messages associated with the claim available to
other workers.

The template is as follows:

.. code:: http

    DELETE {endpoint}/queues/{queue_name}/claims/{claim_id}

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.

Following are examples of a Release Claim request and response:

.. code:: bash

    curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/claims/51ca011c821e7250f344efd6 \
    -H "Content-type: application/json" \
    -H "X-Auth-Token: " \
    -H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830"  \
    -H "Accept: application/json" \
    -H "X-Project-Id: "

.. code:: http

    HTTP/1.1 204 No Content

Delete Queue
------------

The Delete Queue operation immediately deletes a queue and all of its
existing messages.

The template is as follows:

.. code:: http

    DELETE {endpoint}/queues/{queue_name}

Following are examples of a Delete Queue request and response:

.. code:: bash

    curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue \
    -H "Content-type: application/json" \
    -H "X-Auth-Token: " \
    -H "Accept: application/json" \
    -H "X-Project-Id: "

.. code:: http

    HTTP/1.1 204 No Content