<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
        <!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
                 <imageobject>
                  <imagedata fileref="img/Check_mark_23x20_02.svg"
                             format="SVG" scale="60"/>
                </imageobject>
              </inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
                 <imageobject>
                  <imagedata fileref="img/Arrow_east.svg"
                             format="SVG" scale="60"/>
                </imageobject>
              </inlinemediaobject>'>
]>
<book xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:m="http://www.w3.org/1998/Math/MathML"
    xmlns:html="http://www.w3.org/1999/xhtml"
    version="5.0" xml:id="mq-gettingstarted">
    <title>Message Queuing API v1 Getting Started Guide</title>
    <titleabbrev>Message Queuing Getting Started Guide</titleabbrev>
    <info>
        <author>
            <personname>
                <firstname/>
                <surname/>
            </personname>
<!--            <affiliation>
                <orgname>OpenStack Foundation</orgname>
            </affiliation> -->
        </author>
<!--        <copyright>
            <year>2013</year>
            <year>2014</year>
            <holder>OpenStack Foundation</holder>
        </copyright> -->
        <releaseinfo>API v1</releaseinfo>
        <productname>Message Queuing</productname>
        <pubdate>2014-02-20</pubdate>
        <!--If you leave the <pubdate> element empty, the build system inserts today's date automatically.   -->
        <legalnotice role="rs-api">
            <annotation>
                <remark>Copyright details are filled in by the build
                    system.</remark>
            </annotation>
        </legalnotice>
        <abstract>
            <para>This document is intended for software developers interested in developing
                applications using the Message Queuing Application Programming Interface
                    (<abbrev>API</abbrev>).</para>
        </abstract>
        <revhistory>
            <revision>
                <date>2014-02-20</date>
                <revdescription>
                    <para>Initial document for OpenStack incubation
                        incubation.</para>
                </revdescription>
            </revision>
            <revision>
                <date>2014-08-30</date>
                <revdescription>
                    <para>The <parameter>partial</parameter> attribute is no longer supported.</para>
                </revdescription>
            </revision>
        </revhistory>
    </info>
    <chapter xml:id="doc-change-history">
        <title>Document Change History</title>
        <para>This version of the document replaces and obsoletes all
            earlier versions. The most recent changes are described in
            the following table:</para>
        <?rax revhistory?>
    </chapter>
    <chapter xml:id="DB_Overview"
        xmlns:svg="http://www.w3.org/2000/svg"
        xmlns:m="http://www.w3.org/1998/Math/MathML"
        xmlns:html="http://www.w3.org/1999/xhtml">
        <title>Overview</title>
        <para>Message Queuing is a RESTful API-based messaging service that supports distributed web
            applications. A message service such as Message Queuing is a vital component of large,
            distributed web applications. You can use Message Queuing for public, private, and
            hybrid cloud environments.</para>
        <para>As you develop distributed web applications, you often have multiple agents set up to
            complete sets of tasks for those applications. These tasks can be anything from creating
            users to deleting blocks of storage. Message Queuing provides a simple interface to
            create these tasks as queues, messages, and claims and to post, claim, read, and delete
            them as the tasks are needed and performed.</para>
        <para>Message Queuing handles the distribution of tasks, but it does not necessarily manage
            the order of the tasks. Applications handle the workflow at a higher level.</para>
        <para>Message Queuing is based on the OpenStack Zaqar project.</para>
        <para>This guide explains how to access and start using the API so that you can begin to use
            Message Queuing for your applications. Instructions are given for how to properly enter
            the necessary URLs, using cURL, to set up and use a basic set of Message Queuing
            operations.</para>
        <section xml:id="core_concepts">
            <title>Prerequisites for Running Examples</title>
            <para xmlns:wadl="http://wadl.dev.java.net/2009/02">In
                order to run the examples in this guide, you must have
                the following prerequisites:</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>A Cloud account</para>
                </listitem>
                <listitem>
                    <para>A username and password, as
                        specified during registration</para>
                </listitem>
                <listitem>
                    <para>Prior knowledge of HTTP/1.1
                        conventions</para>
                </listitem>
                <listitem>
                    <para>Basic familiarity with Cloud and RESTful
                        APIs</para>
                </listitem>
            </itemizedlist>
        </section>
        <section xml:id="how_mq_works">
            <title>How Message Queuing Works</title>
            <para>Following is an overview of how Message Queuing works. For definitions of Message
                Queuing terms, see the <xref linkend="glossary-d1e018"/>.</para>
            <orderedlist>
                <listitem>
                    <para>You create a queue to which producers or
                        publishers post messages.</para>
                </listitem>
                <listitem>
                    <para>Workers (consumers or subscribers) claim or
                        get a message from the queue, complete the
                        work in that message, and delete the
                        message.</para>
                    <para>If a worker will be off-line before it
                        completes the work in a message, the worker
                        can retire the claim's time to live (TTL),
                        putting the message back into the queue for
                        another worker to claim.</para>
                </listitem>
                <listitem>
                    <para>Subscribers monitor the claims from these
                        queues to track activity and help troubleshoot
                        errors.</para>
                </listitem>
            </orderedlist>
            <para>For the majority of use cases, Message Queuing is not responsible for the ordering
                of messages. However, if there is only a single producer, Message Queuing ensures
                that messages are handled in a First In, First Out (FIFO) order.</para>
            <section xml:id="operating_modes">
                <title>Messaging Patterns</title>
                <para>The Message Queuing API supports a variety of
                    messaging patterns including the following:</para>
                <itemizedlist>
                    <listitem>
                        <para>Task distribution</para>
                    </listitem>
                    <listitem>
                        <para>Event broadcasting</para>
                    </listitem>
                    <listitem>
                        <para>Point-to-point messaging</para>
                    </listitem>
                </itemizedlist>
            </section>
            <section xml:id="task_distribution">
                <title>Task distribution</title>
                <para>The task distribution pattern has the following
                    characteristics:</para>
                <itemizedlist>
                    <listitem>
                        <para>A producer is programmed to send messages to a
                            queue.</para>
                    </listitem>
                    <listitem>
                    <para>Multiple workers (or consumers) are programmed to
                        monitor a queue.</para>
                    </listitem>
                    <listitem>
                        <para>Only one worker can claim a message so that
                            no other worker can claim the message and
                            duplicate the work.</para>
                    </listitem>
                    <listitem>
                        <para>The worker must delete the message when work
                            is done.</para>
                    </listitem>
                    <listitem>
                        <para>TTL restores a message to an unclaimed state
                            if the worker never finishes.</para>
                    </listitem>
                </itemizedlist>
                <para>This pattern is ideal for dispatching jobs to multiple
                    processors.</para>
            </section>
            <section xml:id="event_broadcasting">
                <title>Event Broadcasting</title>
                <para>Characteristics of the event broadcasting pattern
                    are:</para>
                <itemizedlist>
                    <listitem>
                        <para>The publisher sends messages to a
                            queue.</para>
                    </listitem>
                    <listitem>
                        <para>Multiple observers (or subscribers) get the
                            messages in the queue.</para>
                    </listitem>
                    <listitem>
                        <para>Multiple observers take action on each
                            message.</para>
                    </listitem>
                    <listitem>
                        <para>Observers send a marker to skip messages
                            already seen.</para>
                    </listitem>
                    <listitem>
                        <para>TTL eventually deletes messages.</para>
                    </listitem>
                </itemizedlist>
                <para>This pattern is ideal for notification of events to
                    multiple observers at once.</para>
            </section>
            <section xml:id="point_to_point">
                <title>Point-to-point messaging</title>
                <para>Characteristics of the point-to-point messaging
                    pattern are:</para>
                <itemizedlist>
                    <listitem>
                        <para>The publisher sends messages to a queue.</para>
                    </listitem>
                    <listitem>
                        <para>The consumer gets the messages in the queue.</para>
                    </listitem>
                    <listitem>
                        <para>The consumer can reply with the result of
                            processing a message by sending another message
                            to the same queue (queues are duplex by
                            default).</para>
                    </listitem>
                    <listitem>
                        <para>The publisher gets replies from the queue.</para>
                    </listitem>
                    <listitem>
                        <para>The consumer sends a marker to skip messages
                            already seen.</para>
                    </listitem>
                    <listitem>
                        <para>TTL eventually deletes messages.</para>
                    </listitem>
                </itemizedlist>
                <para>This pattern is ideal for communicating with a
                    specific client, especially when a reply is desired
                    from that client.</para>
            </section>
            <section xml:id="cloud-queuing-actions">
                <title>Message Queuing Operations</title>
                <para>This section lists all of the operations that are available in the Message
                    Queuing API. This document uses some of the most common operations in <xref
                        linkend="stepping_through_the_api"/>.</para>
                <para>For details about all of the operations, see the <citetitle>Message Queuing
                        API v1 Reference</citetitle>.</para>
                <section xml:id="homeDocument">
                    <title>Home Document</title>
                    <para>The following operation is available for the
                        home document:</para>
                    <itemizedlist>
                        <listitem>
                            <para>Get Home Document</para>
                        </listitem>
                    </itemizedlist>
                </section>
                <section xml:id="queue-actions">
                    <title>Queues</title>
                    <para>The following operations are available for
                        queues:</para>
                    <itemizedlist>
                        <listitem>
                            <para>Create Queue</para>
                        </listitem>
                        <listitem>
                            <para>List Queues</para>
                        </listitem>
                        <listitem>
                            <para>Check Queue Existence</para>
                        </listitem>
                        <listitem>
                            <para>Set Queue Metadata</para>
                        </listitem>
                        <listitem>
                            <para>Get Queue Metadata</para>
                        </listitem>
                        <listitem>
                            <para>Get Queue Stats</para>
                        </listitem>
                        <listitem>
                            <para>Delete Queue</para>
                        </listitem>
                    </itemizedlist>
                </section>
                <section xml:id="message-actions">
                    <title>Messages</title>
                    <para>The following operations are available for
                        messages:</para>
                    <itemizedlist>
                        <listitem>
                            <para>Post Message</para>
                        </listitem>
                        <listitem>
                            <para>Get Messages</para>
                        </listitem>
                        <listitem>
                            <para>Get a Specific Message</para>
                        </listitem>
                        <listitem>
                            <para>Get a Set of Messages by ID</para>
                        </listitem>
                        <listitem>
                            <para>Delete Message</para>
                        </listitem>
                        <listitem>
                            <para>Delete a Set of Messages by
                                ID</para>
                        </listitem>
                    </itemizedlist>
                </section>
                <section xml:id="claim-actions">
                    <title>Claims</title>
                    <para>The following operations are available for
                        claims:</para>
                    <itemizedlist>
                        <listitem>
                            <para>Claim Messages</para>
                        </listitem>
                        <listitem>
                            <para>Query Claim</para>
                        </listitem>
                        <listitem>
                            <para>Update Claim</para>
                        </listitem>
                        <listitem>
                            <para>Release Claim</para>
                        </listitem>
                    </itemizedlist>
                </section>
            </section>
            <section xml:id="use_cases">
                <title>Use Cases</title>
                <para>Queuing systems are used to coordinate tasks
                    within an application. Here are some
                    examples:</para>
                <itemizedlist>
                    <listitem>
                        <para><emphasis role="bold">Backup</emphasis>:
                            A backup application might use a queuing
                            system to connect the actions that users
                            do in the a control panel to the
                            customer's backup agent on a server. When
                            a customer wants to start a backup, they
                            simply choose "start backup" on a panel.
                            Doing so causes the producer to put a
                            "startBackup" message into the queue.
                            Every few minutes, the agent on the
                            customers server (the worker) checks the
                            queue to see if it has any new messages to
                            act on. The agent claims the "startBackup"
                            message and kicks off the backup on the
                            customer's server.</para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold"
                            >Storage</emphasis>: Gathering statistics
                            for a large, distributed storage system
                            can be a long process. The storage system
                            can use a queuing system to ensure that
                            jobs complete, even if one initially
                            fails. Since messages are not deleted
                            until after the worker has completed the
                            job, the storage system can make sure that
                            no job goes undone. If the worker fails to
                            complete the job, the message stays in the
                            queue to be completed by another server.
                            In this case, a worker claims a message to
                            perform a statistics job, but the claim's
                            TTL expired and the message is put back
                            into the queue when the job took too long
                            to complete (meaning that it most likely
                            failed). By giving the claim a TTL,
                            applications can protect themselves from
                            workers going off-line while processing a
                            message. After a claim's TTL expires, the
                            message is put back into the queue for
                            another worker to claim.</para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold">Email</emphasis>:
                            The team for an email application is
                            constantly migrating customer email from
                            old versions to newer ones, so they
                            develop a tool to let customers do it
                            themselves. The migrations take a long
                            time, so they cannot be done with single
                            API calls, or by a single server. When a
                            user starts a migration job from their
                            portal, the migration tool sends messages
                            to the queue with details of how to run
                            the migration. A set of migration engines,
                            the consumers in this case, periodically
                            check the queues for new migration tasks,
                            claim the messages, perform the migration,
                            and update a database with the migration
                            details. This process allows a set of
                            servers to work together to accomplish
                            large migrations in a timely manner.
                        </para>
                    </listitem>
                </itemizedlist>
                <para>Following are some generic use cases for Message Queuing:</para>
                <itemizedlist>
                    <listitem>
                        <para>Distribute tasks among multiple workers (transactional
                            job queues)</para>
                    </listitem>
                    <listitem>
                        <para>Forward events to data collectors (transactional event
                            queues)</para>
                    </listitem>
                    <listitem>
                        <para>Publish events to any number of subscribers
                            (event broadcasting)</para>
                    </listitem>
                    <listitem>
                        <para>Send commands to one or more agents
                            (point-to-point messaging or event broadcasting)</para>
                    </listitem>
                    <listitem>
                        <para>Request an action or get information from a Remote
                            Procedure Call (RPC) agent (point-to-point
                            messaging)</para>
                    </listitem>
                </itemizedlist>
            </section>
        </section>
    </chapter>
    <chapter xml:id="prerequisites">
        <title>Send Requests to the API</title>
        <para>You have several options for sending requests through an
            API:</para>
        <itemizedlist spacing="compact">
            <listitem>
                <para>Developers and testers may prefer to use cURL,
                    the command-line tool from <link
                        xlink:href="http://curl.haxx.se/"
                        >http://curl.haxx.se/</link>.</para>
                <para>With cURL you can send HTTP requests and receive
                    responses back from the command line.</para>
            </listitem>
            <listitem>
                <para>If you like to use a more graphical interface,
                    the REST client for Firefox also works well for
                    testing and trying out commands, see <link
                        xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
                        >https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>.
                </para>
            </listitem>
            <listitem>
                <para>You can also download and install rest-client, a
                    Java application to test RESTful web services,
                    from <link
                        xlink:href="http://code.google.com/p/rest-client/"
                        >http://code.google.com/p/rest-client/</link>.
                </para>
            </listitem>
        </itemizedlist>
        <section xml:id="using_curl">
            <title>Sending API Requests Using cURL</title>
            <para>cURL is a command-line tool that is available in
                UNIX® system-based environments and Apple Mac OS X®
                systems, and can be downloaded for Microsoft Windows®
                to interact with the REST interfaces. For more
                information about cURL, visit <link
                    xlink:href="http://curl.haxx.se/"
                    >http://curl.haxx.se/</link>.</para>
            <para>cURL enables you to transmit and receive HTTP
                requests and responses from the command line or from
                within a shell script. As a result, you can work with
                the REST API directly without using one of the client
                APIs.</para>
            <para>The following cURL command-line options are used in
                this guide to run the examples.</para>
            <table rules="all">
                <caption>cURL Command-Line Options</caption>
                <col width="30%"/>
                <col width="70%"/>
                <thead>
                    <tr>
                        <th>Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>-d</code></td>
                        <td>Sends the specified data in a
                                <code>POST</code> request to the HTTP
                            server.</td>
                    </tr>
                    <tr>
                        <td><code>-i</code></td>
                        <td>Includes the HTTP header in the
                            output.</td>
                    </tr>
                    <tr>
                        <td><code>-H HEADER</code></td>
                        <td>Specifies an HTTP header in the
                            request.</td>
                    </tr>
                    <tr>
                        <td><code>-X</code></td>
                        <td>Specifies the request method to use when
                            communicating with the HTTP server. The
                            specified request is used instead of the
                            default method, which is GET. For example,
                                <code>-X PUT</code> specifies to use
                            the <code>PUT</code> request method.</td>
                    </tr>
                </tbody>
            </table>
            <note>
                <para>If you have the tools, you can run the cURL JSON
                    request examples with the following options to
                    format the output from cURL: <command>&lt;curl
                        JSON request example> | python
                        -mjson.tool</command>.</para>
            </note>
        </section>
        <section xml:id="Copying-and_Pasting-cURL-d1e003">
            <title>Copying and Pasting cURL Request Examples into a
                Terminal Window</title>
            <para>To run the cURL request examples shown in this guide
                    (<xref linkend="stepping_through_the_api"/>) on
                Linux or Mac systems, perform the following
                actions:</para>
            <orderedlist>
                <listitem>
                    <para>Copy and paste each example from the HTML
                        version of this guide into an ASCII text
                        editor (for example, vi or TextEdit). You can
                        click on the small document icon to the right
                        of each request example to select it.</para>
                </listitem>
                <listitem>
                    <para>Modify each example with your required
                        account information and so forth, as detailed
                        in this guide.</para>
                </listitem>
                <listitem>
                    <para>After you are finished modifying the text
                        for the cURL request example with your
                        information (for example,<emphasis role="bold"
                                ><literal>your_username</literal></emphasis>
                        and <emphasis role="bold"
                                ><literal>your_api_key</literal></emphasis>),
                        paste it into your terminal window.</para>
                </listitem>
                <listitem>
                    <para>Press <guilabel>Enter</guilabel> to run the
                        cURL command.</para>
                </listitem>
            </orderedlist>
            <note>
                <para>The carriage returns in the cURL request
                    examples that are part of the cURL syntax are
                    escaped with a backslash (\) in order to avoid
                    prematurely terminating the command. However, you
                    should not escape carriage returns inside the JSON
                    message within the command.</para>
            </note>
            <tip>
                <para>If you have trouble copying and pasting the
                    examples as described, try typing the entire
                    example on one long line, removing all the
                    backslash line continuation characters.</para>
            </tip>
        </section>
    </chapter>
    <chapter xml:id="Generating_Auth_Token">
        <title>Generate an Authentication Token</title>
        <para>You can use <link xlink:href="http://curl.haxx.se/">cURL</link> to try the
            authentication process in two steps: get a token, and send the token to a service.<orderedlist>
                <listitem>
                    <para>Get an authentication token by providing your user name and either your
                        API key or your password. Here are examples of both approaches:</para>
                    <para>You can request a token by providing your user name and your
                        password.</para>
                    <programlisting>$ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</programlisting>
                    <para>Successful authentication returns a token which you can use as evidence
                        that your identity has already been authenticated. To use the token, pass it
                        to other services as an <code>X-Auth-Token</code> header.</para>
                    <para>Authentication also returns a service catalog, listing the endpoints you
                        can use for Cloud services.</para>
                </listitem>
                <listitem>
                    <para>Use the authentication token to send a <command>GET</command> to a service
                        you would like to use.</para>
                </listitem>
            </orderedlist></para>
        <para>Authentication tokens are typically valid for 24 hours. Applications should be
            designed to re-authenticate after receiving a 401 (Unauthorized) response from a service
            endpoint.</para>
        <note>
            <para>If you programmatically parse an authentication response, be aware that service
                names are stable for the life of the particular service and can be used as keys. You
                should also be aware that a user's service catalog can include multiple
                uniquely-named services that perform similar functions.</para>
        </note>
    </chapter>
    <chapter xml:id="commonHeaders">
        <title>Common Headers</title>
        <para>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.</para>
        <table rules="all">
            <caption>Common Headers</caption>
            <col width="30%"/>
            <col width="70%"/>
            <thead>
                <tr>
                    <th>Header</th>
                    <th>Description</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>Host</td>
                    <td>Host name of the API</td>
                </tr>
                <tr>
                    <td>Date</td>
                    <td>Current date and time</td>
                </tr>
                <tr>
                    <td>Accept</td>
                    <td>Media type to use. Initially, only
                            <code>application/json</code> is
                        supported. <emphasis role="bold">Note: The
                                <code>Accept</code> header is
                            required.</emphasis></td>
                </tr>
                <tr>
                    <td>Accept-Encoding</td>
                    <td>Specifies that the agent accepts gzip-encoded
                        response bodies</td>
                </tr>
                <tr>
                    <td>Content-Type</td>
                    <td><code>application/json</code></td>
                </tr>
                <tr>
                    <td>Content-Length</td>
                    <td>For <command>POST</command> or
                            <command>PUT</command> requests, the
                        length in bytes of the message document being
                        submitted</td>
                </tr>
                <tr>
                    <td>X-Auth-Token</td>
                    <td>Authorization token</td>
                </tr>
                <tr>
                    <td>X-Project-Id</td>
                    <td>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).</td>
                </tr>
                <tr>
                    <td>Client-ID</td>
                    <td>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.
                            <emphasis role="bold">Note: All
                            message-related operations require the use
                            of <code>Client-ID</code> in the headers
                            to ensure that messages are not echoed
                            back to the client that posted them,
                            unless the client explicitly requests
                            this.</emphasis></td>
                </tr>
            </tbody>
        </table>
    </chapter>
    <chapter xml:id="stepping_through_the_api">
        <title>Working with the Message Queuing API</title>
        <para>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.</para>
        <para>For a complete list of operations available for Message Queuing, see <xref
                linkend="cloud-queuing-actions"/>. Each operation is fully described in the
                <emphasis role="italic">Message Queuing API v1 Reference</emphasis>.</para>
        <section xml:id="create_queue">
            <title>Create Queue</title>
            <para>The Create Queue operation creates a queue in the
                region of your choice.</para>
            <para>The body of the PUT request is empty.</para>
            <para>The template is as follows:</para>
            <para>
                <programlisting language="json">PUT {endpoint}/queues/{queue_name}</programlisting>
            </para>
            <para>The <parameter>queue_name</parameter> parameter
                specifies the name to give the queue. The name
                    <emphasis role="italic">must not</emphasis> exceed
                64 bytes in length and is limited to US-ASCII letters,
                digits, underscores, and hyphens.</para>
            <para>Following are examples of a Create Queue request and
                response:</para>
            <example>
                <title>cURL Create Queue Request</title>
                <programlisting language="bash">curl -i -X PUT https://queues.api.openstack.org/v1/queues/samplequeue \
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
-H "Accept: application/json" \
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
            </example>
            <example>
                <title>Create Queue Response</title>
                <programlisting language="json">HTTP/1.1 201 Created
Content-Length: 0
Location: /v1/queues/samplequeue</programlisting>
            </example>
        </section>
        <section xml:id="insert_messages">
            <title>Post Message</title>
            <para>The Post Message operation inserts one or more
                messages in a queue.</para>
            <para>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.</para>
            <para>The template is as
                follows:<programlisting language="json">POST {endpoint}/queues/{queue_name}/messages</programlisting></para>
            <para>The client specifies only the <tag class="attribute"
                    >body</tag> and <tag class="attribute">ttl</tag>
                attributes for the message. Metadata, such as <tag
                    class="attribute">id</tag> and <tag
                    class="attribute">age</tag>, is added.</para>
            <para>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.</para>
            <para>If a server-side error occurs during the processing
                of the submitted messages, a partial list is returned.
                The <parameter>partial</parameter> attribute is set to
                    <parameter>true</parameter>, and the client tries
                to post the remaining messages again.
            </para>
            <important>
                <para>The <parameter>partial</parameter> 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.
                </para>
            </important>
            <para>
                The <parameter>body</parameter> attribute specifies an
                arbitrary document that constitutes the body of the
                message being sent.</para>
            <para>The following rules apply for the maximum size:<itemizedlist>
                    <listitem>
                        <para>The size is limited to 256 KB for the
                            entire request body (as-is), including
                            whitespace.</para>
                    </listitem>
                    <listitem>
                        <para>The maximum size of posted messages is
                            the maximum size of the entire request
                            document (rather than the sum of the
                            individual message <code>body</code> field
                            values as it was earlier releases). On
                            error, the client is notified of by how
                            much the request exceeded the
                            limit.</para>
                    </listitem>
                </itemizedlist></para>
            <!-- 2014-01-17 cyr: Per email from Kurt today, the following information is now outdated and is replaced with the information above.
            <para>
                excluding whitespace. If multiple messages are
                included in the request, this limit also applies to
                the sum of the message bodies. For example, you can
                have one message body of 256 KB, or up to 10 messages
                for which the sum of the message bodies is 256 KB. An
                    HTTP<code>400 Bad Request</code> response code is
                triggered if a single message body or the sum of
                multiple message bodies exceeds 256 KB in a single
                request.</para>
-->
            <para>The document <emphasis role="italic">must</emphasis> be valid JSON. (The Message
                Queuing service validates it.)</para>
            <para>The <parameter>ttl</parameter> 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).</para>
            <note>
                <para>The server might not actually delete the
                    message until its age reaches <tag
                        class="attribute">(ttl + 60)</tag> seconds. So
                    there might be a delay of 60 seconds after the
                    message expires before it is deleted.</para>
            </note>
            <para>The following are examples of a Post Message request
                and response:</para>
            <example>
                <title>cURL Post Message Request</title>
                <programlisting language="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: <emphasis role="bold">your_auth_token</emphasis>" \
-H "Accept: application/json" \
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
            </example>
            <example>
                <title>Post Message Response</title>
                <programlisting language="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"]}
</programlisting>
            </example>
        </section>
        <section xml:id="Claim_messages">
            <title>Claim Messages</title>
            <para>The Claim Messages operation claims a set of messages (up to the value of the
                    <parameter>limit</parameter> 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 <code>204 No Content</code> response
                code.</para>
            <para>The template is as follows:</para>
            <programlisting language="json">POST {endpoint}/queues/{queue_name}/claims{?limit}
Content-Type: application/json

{
    "ttl": {claim_ttl},
    "grace": {message_grace}
}</programlisting>
            <para>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 <citetitle>Message
                    Queuing API v1 Reference</citetitle> 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.</para>
            <para>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.</para>
            <para>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.)</para>
            <para>The <parameter>limit</parameter> parameter specifies
                the number of messages to claim. The <parameter>limit</parameter> 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.</para>
            <para>The <parameter>ttl</parameter> 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).</para>
            <para>The <parameter>grace</parameter> 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</para>
            <para>Following are examples of a Claim Messages request
                and response:</para>
            <example>
                <title>cURL Claim Messages Request</title>
                <programlisting language="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: <emphasis role="bold">your_auth_token</emphasis>" \
-H "Accept: application/json" \
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
            </example>
            <example>
                <title>Claim Messages Response</title>
                <programlisting language="json">HTTP/1.1 201 OK
Content-Length: 164
Content-Type: application/json; charset=utf-8
Location: /v1/queues/samplequeue/claims/51ca011c821e7250f344efd6
X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>

[
  {
    "body": {
      "event": "BackupStarted"
    },
    "age": 124,
    "href": "\/v1\/queues\/samplequeue\/messages\/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6",
    "ttl": 300
  }
]</programlisting>
            </example>
        </section>
        <section xml:id="Delete_messages">
            <title>Delete Message with Claim ID</title>
            <para>The Delete Message operations deletes
                messages.</para>
            <para>The template is as
                follows:<programlisting language="json">DELETE {endpoint}/queues/{queue_name}/messages/{message_id}{?claim_id}
</programlisting></para>
            <para>The <parameter>message_id</parameter> parameter
                specifies the message to delete.</para>
            <para>The <parameter>claim_id</parameter> 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.</para>
            <para>Following are examples of a Delete Message request
                and response:</para>
            <example>
                <title>cURL Delete Message Request</title>
                <programlisting language="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: <emphasis role="bold">your_auth_token</emphasis>" \
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
-H "Accept: application/json" \
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
            </example>
            <example>
                <title>Delete Message Response</title>
                <programlisting language="json">HTTP/1.1 204 No Content</programlisting>
            </example>
        </section>
        <section xml:id="Delete_claim">
            <title>Release Claim</title>
            <para>The Release Claim operation immediately releases a
                claim, making any remaining, undeleted) messages
                associated with the claim available to other
                workers.</para>
            <para>The template is as follows:</para>
            <programlisting language="json">DELETE {endpoint}/queues/{queue_name}/claims/{claim_id}</programlisting>
            <para>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.</para>
            <para>Following are examples of a Release Claim request
                and response:</para>
            <example>
                <title>cURL Release Claim Request</title>
                <programlisting language="bash">curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/claims/51ca011c821e7250f344efd6 \
-H "Content-type: application/json" \
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830"  \
-H "Accept: application/json" \
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
            </example>
            <example>
                <title>Release Claim Response</title>
                <programlisting language="json">HTTP/1.1 204 No Content</programlisting>
            </example>
        </section>
        <section xml:id="Delete_queue">
            <title>Delete Queue</title>
            <para>The Delete Queue operation immediately deletes a
                queue and all of its existing messages.</para>
            <para>The template is as
                follows:<programlisting language="json">DELETE {endpoint}/queues/{queue_name}</programlisting></para>
            <para>Following are examples of a Delete Queue request and
                response:</para>
            <example>
                <title>cURL Delete Queue Request</title>
                <programlisting language="bash">curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue \
-H "Content-type: application/json" \
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
-H "Accept: application/json" \
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
            </example>
            <example>
                <title>Delete Queue Response</title>
                <programlisting language="json">HTTP/1.1 204 No Content
</programlisting>
            </example>
        </section>
    </chapter>
    <chapter xml:id="additional-resources">
        <title>Additional Resources</title>
        <para>For more information about using the API, see the <citetitle>Message Queuing API v1
                Reference</citetitle>. All you need to get started with Message Queuing is the
            getting started guide, the reference, and your Cloud account.</para>
        <para>For information about the OpenStack Zaqar API, see
                <link
                xlink:href="https://wiki.openstack.org/wiki/Zaqar/specs/api/v1"
                >wiki.openstack.org/wiki/Zaqar/specs/api/v1</link>.</para>
        <para>This API uses standard HTTP 1.1 response codes as
            documented at <link
                xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
                >www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.
        </para>
    </chapter>
    <glossary xml:id="glossary-d1e018">
        <title>Glossary</title>
        <glossentry xml:id="claim-d1e017">
            <glossterm>Claim</glossterm>
            <glossdef>
                <para>The process of a worker checking out a message
                    to perform a task. Claiming a message prevents
                    other workers from attempting to process the same
                    messages.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Claim TTL</glossterm>
            <glossdef>
                <para>Defines how long a message will be in claimed
                    state. A message can be claimed by one worker at a
                    time.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Consumer</glossterm>
            <glossdef>
                <para>A server that claims messages from the
                    queue.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="message-d1e016">
            <glossterm>Message</glossterm>
            <glossdef>
                <para>A task, a notification, or any meaningful data
                    that a producer or publisher sends to the queue. A
                    message exists until it is deleted by a recipient
                    or automatically by the system based on a TTL
                    (time-to-live) value.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Message TTL</glossterm>
            <glossdef>
                <para>Defines how long a message will be accessible.
                </para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Producer </glossterm>
            <glossdef>
                <para>A server or application that sends messages to
                    the queue.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Producer - Consumer</glossterm>
            <glossdef>
                <para>A pattern where each worker application that
                    reads the queue has to claim the message in order
                    to prevent duplicate processing. Later, when work
                    is done, the worker is responsible for deleting
                    the message. If message is not deleted in a
                    predefined time, it can be claimed by other
                    workers.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Publisher</glossterm>
            <glossdef>
                <para>A server or application that posts messages to
                    the queue with the intent to distribute
                    information or updates to multiple
                    subscribers.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>Publisher - Subscriber</glossterm>
            <glossdef>
                <para>A pattern where all worker applications have
                    access to all messages in the queue. Workers
                    cannot delete or update messages.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="queue-d1e019">
            <glossterm>Queue</glossterm>
            <glossdef>
                <para>The entity that holds messages. Ideally, a queue
                    is created per work type. For example, if you want
                    to compress files, you would create a queue
                    dedicated to this job. Any application that reads
                    from this queue would only compress files.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="subscriber-d1e018">
            <glossterm>Subscriber</glossterm>
            <glossdef>
                <para>An observer that watches messages like an RSS
                    feed but does not claim any messages.</para>
            </glossdef>
        </glossentry>
        <glossentry>
            <glossterm>TTL</glossterm>
            <glossdef>
                <para>Time-to-live value.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="worker-d1e018">
            <glossterm>Worker</glossterm>
            <glossdef>
                <para>A client that claims messages from the queue and
                    performs actions based on those messages.</para>
            </glossdef>
        </glossentry>
    </glossary>
</book>
