openstack/zaqar
Code Issues Proposed changes
65bf61df13
zaqar/doc/user-guide/zaqar-api-ref/os-zaqar-apiRef.xml
kgriffs aaae850f5f Update use cases to align with dev guide and positioning 
This patch updates the language in the user guide to be more
consistent with our current positioning of Zaqar, and to
clarify some confusion around individual use cases.

Change-Id: I32d75b3d4bec6ad758ef27fc3b5daf32651b1a44
2014-08-19 09:49:07 -05:00

1823 lines
65 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<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="os-zaqar-apiRef">
<title>Message Queuing API v1 Reference</title>
<titleabbrev>Message Queuing API Reference</titleabbrev>
<info>
<!-- <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>
<!--Note that the <productname> text matches the first few words of the title. The build system splits the title into productname + rest of title on the pdf cover.-->
<!--If you leave the <pubdate> element empty, the build system inserts today's date automatically. -->
<legalnotice role="apache2">
<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.</para>
</revdescription>
</revision>
</revhistory>
</info>
<preface xml:id="preface">
<title>Preface</title>
<para>Message Queuing is an open source, scalable, and highly available message and
notifications service. Message Queuing supports a variety of messaging patterns. Users of this
service can create and manage a producer-consumer or a publisher-subscriber model (<xref
linkend="operating_modes"/>) from one simple API. Unlimited queues and messages give Message
Queuing users the flexibility they need to create powerful web applications in the
cloud.</para>
<para>Message Queuing consists of a few basic components: queues, messages, claims, and
statistics. In the producer-consumer model, users create queues in which producers, or
servers, can post messages. Workers, or consumers, can then claim those messages and delete
them after they complete the actions associated with the messages. A single claim can contain
multiple messages, and administrators can query claims for status.</para>
<para>In the publisher-subscriber model, messages are posted to a
queue as in the producer-consumer model, but messages are never
claimed. Instead, subscribers, or watchers, send
<command>GET</command> requests to pull all messages that have
been posted since their last request. In this model, a message
remains in the queue, unclaimed, until the message's time to
live (TTL) has expired.</para>
<para>In both of these models, administrators can get queue
statistics that display the most recent and oldest messages, the
number of unclaimed messages, and more.</para>
<section xml:id="Intended_Audience-d1e166">
<title>Intended Audience</title>
<para>This document is intended for software developers who are interested in developing
applications that use the Message Queuing API. It assumes that you have the following
skills:</para>
<itemizedlist>
<listitem>
<para>RESTful web services</para>
</listitem>
<listitem>
<para>HTTP/1.1 conventions</para>
</listitem>
<listitem>
<para>JSON data serialization formats</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="Document_Change_History-d1e166">
<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?>
</section>
<?hard-pagebreak?>
<!-- <section xml:id="Additional_Resources-d1e346">
<title>Additional Resources</title>
<para>You can download the most current version of this document
from the OpenStack Docs website at <link
xlink:href="http://docs.openstack.org">
http://docs.openstack.org</link>.</para>
</section> -->
</preface>
<chapter xml:id="Concepts-dle001">
<title>Concepts</title>
<para>To use the Message Queueing API effectively, you should
understand the key concepts described in this section.</para>
<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_1"/>.</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>
<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 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 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>
<section xml:id="Use-Cases-d1e001">
<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>
</chapter>
<chapter xml:id="Gen_API_Info-de01">
<title>General API Information</title>
<para>The Message Queuing API is implemented using a RESTful web service interface. Like other
OpenStack projects, Message Queuing shares a common token-based authentication system that
allows seamless access between products and services.</para>
<note>
<para>All requests to authenticate against and operate the
service are performed using SSL over HTTP (HTTPS) on TCP port
443.</para>
</note>
<section xml:id="Authentication-d1e647">
<title>Authentication</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>
</section>
<section xml:id="Request_Response_Types-d1e903">
<title>Request and Response Types</title>
<para>The Message Queuing API supports JSON data serialization formats. You specify the
request format by using the <code>Content-Type</code> header. The request format is
<emphasis role="italic">required</emphasis> for calls that have a request body. You can
specify the response format in requests either by using the Accept header or by adding a
<code>.json</code> extension to the request URI. JSON is also used for the response
format.</para>
<table rules="all">
<caption>Response Format</caption>
<?dbfo keep-together="always"?>
<thead>
<tr align="center">
<td>Format</td>
<td>Accept Header</td>
<td>Query Extension</td>
<td>Default</td>
</tr>
</thead>
<tbody>
<tr>
<td>JSON</td>
<td>application/json</td>
<td>.json</td>
<td>Yes</td>
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="Limits-d1e1397">
<title>Absolute Limits</title>
<para>Accounts are configured with default thresholds, or limits, that manage capacity and
prevent abuse of the system.</para>
<para>The following table provides details about the absolute limits for the Message Queuing
API.</para>
<note>
<para>These limits are configurable.</para>
</note>
<table rules="all">
<caption>Absolute Limits</caption>
<col width="25%"/>
<col width="35%"/>
<col width="20%"/>
<col width="20%"/>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
<th>Limit</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="6">Limits on Messages and Queues per Request</td>
<td>Number of queue records per page of results when listing queues</td>
<td>1 - 1000</td>
<td>20</td>
</tr>
<tr>
<td>Number of messages per page of results when listing messages</td>
<td>1 - 25</td>
<td>20</td>
</tr>
<tr>
<td>Number of messages that can be posted in a single request</td>
<td>1 - 25</td>
<td>20</td>
</tr>
<tr>
<td>Number of messages that can be claimed at one time</td>
<td>1 - 25</td>
<td>20</td>
</tr>
<tr>
<td>Number of messages that can be deleted in a single bulk delete request</td>
<td>1 - 25</td>
<td>20</td>
</tr>
<tr>
<td>Number of messages that can be requested in a bulk get by ID</td>
<td>1 - 25</td>
<td>20</td>
</tr>
<tr>
<td rowspan="3">Time Limits</td>
<td>Valid range for a message TTL</td>
<td>60 - 1209600 seconds (1 minute to 14 days)</td>
<td>1209600 seconds</td>
</tr>
<tr>
<td>Valid range for a claim TTL</td>
<td>60 - 43200 seconds (1 minute to 12 hours)</td>
<td>43200 seconds</td>
</tr>
<tr>
<td>Valid range for claim grace period</td>
<td>60 - 43200 seconds (1 minute to 12 hours)</td>
<td>43200 seconds</td>
</tr>
<tr>
<td rowspan="2">Data Limits</td>
<td>Queue metadata JSON</td>
<td>Cannot exceed 262144 bytes, including whitespace (256 KB)</td>
<td>65536 bytes</td>
</tr>
<tr>
<td>Message body JSON</td>
<td>Cannot exceed 262144 bytes, including whitespace (256 KB)</td>
<td>262144 bytes</td>
</tr>
</tbody>
</table>
<note>
<para>For the 256 KB data limit for the message body JSON, if multiple messages are included
in the request, this limit also applies to the sum of the message bodies added together.
For example, you may have one message body of 256 KB, or up to 10 messages for which the
sum of the message bodies is 256 KB. A 400 error is triggered if a single message body or
the sum of multiple message bodies exceed 256 KB in a single request.</para>
</note>
</section>
<section xml:id="commonHeaders">
<title>Common Headers</title>
<para>Each request to the Message Queuing API must include certain standard and extended HTTP
headers. 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 desired; 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>Auth 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.</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>
</section>
<section xml:id="datetimeformat">
<title>Date and Time Format</title>
<para>For the display and consumption of date and time values, the Message Queuing service
uses a date format that complies with ISO 8601.</para>
<example>
<title>Service Date and Time Format</title>
<programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
<para>For example, May 19, 2013 at 8:07:08 A.M., GMT-5 would
have the following format:</para>
<programlisting>2013-05-19T08:07:08-05:00</programlisting>
</example>
<para>The following table describes the date and time format
codes.</para>
<table rules="all">
<caption>Explanation of Date and Time Format Codes</caption>
<thead>
<tr>
<td>Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>yyyy</td>
<td>Four-digit year</td>
</tr>
<tr>
<td>MM</td>
<td>Two-digit month</td>
</tr>
<tr>
<td>dd</td>
<td>Two-digit day of at the month</td>
</tr>
<tr>
<td>T</td>
<td>Separator for date and time</td>
</tr>
<tr>
<td>HH</td>
<td>Two-digit hour of the day (00-23)</td>
</tr>
<tr>
<td>mm</td>
<td>Two-digit minutes of the hour</td>
</tr>
<tr>
<td>ss</td>
<td>Two-digit seconds of the minute</td>
</tr>
<tr>
<td>SSS</td>
<td>Three-digit milliseconds of the second</td>
</tr>
<tr>
<td>Z</td>
<td>RFC 822 time zone</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="faults-dle101">
<title>Faults</title>
<para>If any Message Queuing request results in an error, the queuing service returns an
appropriate 4<emphasis role="italic">xx</emphasis> or 5<emphasis role="italic">xx</emphasis>
HTTP status code, and the following information in the body:</para>
<itemizedlist>
<listitem>
<para>Title</para>
</listitem>
<listitem>
<para>Description</para>
</listitem>
<listitem>
<para>Internal code</para>
</listitem>
<listitem>
<para>Link to more information</para>
</listitem>
</itemizedlist>
<para><?rax-fo keep-with-next?> An example of an error message
follows.</para>
<example>
<title>Error Message Example</title>
<programlisting>HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"title": "Unsupported limit",
"description": "The given limit cannot be negative, and cannot be greater than 50.",
"code": 1092,
"link": {
"rel": "help",
"href": "http://docs.example.com/messages#limit",
"text": "API documentation for the limit parameter"
}
}</programlisting>
</example>
<para>Detailed error information for each API operation is
included in the following sections. Additionally, brief error
information is included in each operation description in <xref
linkend="API_Operations_dle001"/>.</para>
<section xml:id="error_Codes_And_Explanations">
<title>Response Codes and Explanations</title>
<para>This section includes response codes and explanations for each of the Message Queuing
API operations. The operations are described in <xref linkend="API_Operations_dle001"
/>.</para>
<section xml:id="create_Queue_Codes">
<title>Create Queue</title>
<para>The following table describes the response codes for
the <command>Create Queue</command> operation.</para>
<table rules="all">
<caption>Descriptions of Create Queue Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>201</td>
<td>Success (created)</td>
</tr>
<tr>
<td>204</td>
<td>Success (already exists)</td>
</tr>
<tr>
<td>400</td>
<td>Queue has a long name (greater than 64 bytes)</td>
</tr>
<tr>
<td>400</td>
<td>Request header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Request header has invalid auth token</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="list_Queues_Codes">
<title>List Queues</title>
<para>The following table describes the response codes for
the <command>List Queues</command> operation.</para>
<table rules="all">
<caption>Descriptions of List Queues Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success</td>
</tr>
<tr>
<td>200</td>
<td>URI has invalid parameter (something other than
<parameter>limit</parameter>,
<parameter>marker</parameter>, or
<parameter>metadata</parameter>)</td>
</tr>
<tr>
<td>204</td>
<td>Request with non-existing value for
<parameter>marker</parameter></td>
</tr>
<tr>
<td>400</td>
<td>Request with negative value for
<parameter>limit</parameter></td>
</tr>
<tr>
<td>400</td>
<td>Request with zero value for
<parameter>limit</parameter></td>
</tr>
<tr>
<td>400</td>
<td>Request with non-boolean value for
<parameter>metadata</parameter></td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Request header has invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Request a non-existing queue</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="delete_Queue_Codes">
<title>Delete Queue</title>
<para>The following table describes the response codes for
the <command>Delete Queue</command> operation.</para>
<table rules="all">
<caption>Descriptions of Delete Queue Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>204</td>
<td>Success</td>
</tr>
<tr>
<td>204</td>
<td>Delete a non-existing queue</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Request header has invalid auth token</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="check_Queue_Exists_Codes">
<title>Check Queue Existence</title>
<para>The following table describes the response codes for
the <command>Check Queue Existence</command>
operation.</para>
<table rules="all">
<caption>Descriptions of Check Queue Existence Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>204</td>
<td>Check a non-existing queue</td>
</tr>
<tr>
<td>404</td>
<td>Request a non-existing queue</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="set_Queue_Metadata_Codes">
<title>Set Queue Metadata</title>
<para>The following table describes the response codes for
the <command>Set Queue Metadata</command>
operation.</para>
<table rules="all">
<caption>Descriptions of Set Queue Metadata Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>204</td>
<td>Success</td>
</tr>
<tr>
<td>400</td>
<td>Request body is empty</td>
</tr>
<tr>
<td>400</td>
<td>Request body is greater than 64 KB</td>
</tr>
<tr>
<td>400</td>
<td>Request body has malformed JSON</td>
</tr>
<tr>
<td>400</td>
<td>Request with non-JSON body</td>
</tr>
<tr>
<td>406</td>
<td>Request header has Accept !=
"application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
<tr>
<td/>
<td>Request with UTF-16 char JSON body</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="get_Queue_Metadata_Codes">
<title>Get Queue Metadata</title>
<para>The following table describes the response codes for
the <command>Get Queue Metadata</command>
operation.</para>
<table rules="all">
<caption>Descriptions of Get Queue Metadata Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success</td>
</tr>
<tr>
<td>200</td>
<td>No metadata exists for the queue</td>
</tr>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Request header has invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Request metadata for a non-existing queue</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="get_Queue_Stats_Codes">
<title>Get Queue Stats</title>
<para>The following table describes the response codes for
the <command>Get Queue Stats</command> operation.</para>
<table rules="all">
<caption>Descriptions of Get Queue Stats Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success</td>
</tr>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Request header has invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Request stats for a non-existing queue</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="post_Message_Codes">
<title>Post Message</title>
<para>The following table describes the response codes for
the <command>Post Message</command> operation.</para>
<table rules="all">
<caption>Descriptions of Post Message Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>201</td>
<td>Success</td>
</tr>
<tr>
<td>201</td>
<td>Post multiple messages in a single request, few of
them succeed (with <parameter>"partial":
true</parameter>)</td>
</tr>
<tr>
<td>400</td>
<td>Post greater than 100 messages with a single
request</td>
</tr>
<tr>
<td>400</td>
<td>Post with request body greater than 4 KB</td>
</tr>
<tr>
<td>400</td>
<td>Post with invalid JSON request body</td>
</tr>
<tr>
<td>400</td>
<td>Post with non-JSON request body</td>
</tr>
<tr>
<td>400</td>
<td>Post with non-JSON message</td>
</tr>
<tr>
<td>400</td>
<td>Post with TTL less than 60</td>
</tr>
<tr>
<td>400</td>
<td>Post with TTL greater than 1209600</td>
</tr>
<tr>
<td>400</td>
<td>Post with non-integer value of TTL</td>
</tr>
<tr>
<td>400</td>
<td>Post with negative value of TTL</td>
</tr>
<tr>
<td>400</td>
<td>Post without TTL in request body</td>
</tr>
<tr>
<td>400</td>
<td>Post without <parameter>"body"</parameter> in
request body</td>
</tr>
<tr>
<td>400</td>
<td>Post with no request body</td>
</tr>
<tr>
<td>400</td>
<td>Post with messages encapsulated in multiple
arrays</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Header has invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Post message to a non-existing queue</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json" </td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
<tr>
<td>503</td>
<td>Post multiple messages in a single request and all
of them fail</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="get_Messages_Codes">
<title>Get Messages</title>
<para>The following table describes the response codes for
the <command>Get Messages</command> operation.</para>
<table rules="all">
<caption>Descriptions of Get Messages Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success (query matched 1 or more messages)</td>
</tr>
<tr>
<td>200</td>
<td>Request message with invalid parameter (something
other than <parameter>marker</parameter>,
<parameter>limit</parameter>, or
<parameter>echo</parameter>)</td>
</tr>
<tr>
<td>204</td>
<td>Success (query has no match)</td>
</tr>
<tr>
<td>204</td>
<td>Request message with non-existing
<parameter>marker</parameter>
</td>
</tr>
<tr>
<td>400</td>
<td>Request message with limit greater than 100</td>
</tr>
<tr>
<td>400</td>
<td>Post with request body greater than 4 KB</td>
</tr>
<tr>
<td>400</td>
<td>Request message with limit less than or equal to 0
</td>
</tr>
<tr>
<td>400</td>
<td>Request message with non-boolean value for
<parameter>echo</parameter>
</td>
</tr>
<tr>
<td>401</td>
<td>Header has invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Request message from a non-existing queue</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json" </td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="get_Set_Of_Messages_Codes">
<title>Get a Set of Messages by ID</title>
<para>The following table describes the response codes for
the <command>Get a Set of Messages by ID</command>
operation.</para>
<table rules="all">
<caption>Descriptions of Get a Set of Messages by ID
Response Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success</td>
</tr>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>400</td>
<td>Request message with limit greater than 100</td>
</tr>
<tr>
<td>401</td>
<td>Post with request body greater than 4 KB</td>
</tr>
<tr>
<td>404</td>
<td>Request message with limit less than or equal to 0
</td>
</tr>
<tr>
<td>404</td>
<td>Request message with non-boolean value for
<parameter>echo</parameter>
</td>
</tr>
<tr>
<td>406</td>
<td>Header has invalid auth token</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="delete_Set_Of_Messages_Codes">
<title>Delete a Set of Messages by ID</title>
<para>The following table describes the response codes for
the <command>Delete a Set of Messages by ID</command>
operation.</para>
<table rules="all">
<caption>Descriptions of Delete a Set of Messages by ID
Response Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>204</td>
<td>Success</td>
</tr>
<tr>
<td>204</td>
<td>Delete message from a non-existing queue</td>
</tr>
<tr>
<td>204</td>
<td>Delete a non-existing message</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Header has invalid auth token</td>
</tr>
<tr>
<td>403</td>
<td>Delete with expired claim ID</td>
</tr>
<tr>
<td>403</td>
<td>Delete with non-existing claim ID</td>
</tr>
<tr>
<td>403</td>
<td>Delete claimed message without providing a claim
ID</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json" </td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="Get_Specific_Message_Codes">
<title>Get a Specific Message</title>
<para>The following table describes the response codes for
the <command>Get a Specific Message</command>
operation.</para>
<table rules="all">
<caption>Descriptions of Get a Specific Message Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success(query matched the message)</td>
</tr>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Header has invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Request message from a non-existing queue</td>
</tr>
<tr>
<td>404</td>
<td>Request a non-existing message</td>
</tr>
<tr>
<td>404</td>
<td>Request an expired message</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json" </td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="delete_Message_Codes">
<title>Delete Message</title>
<para>The following table describes the response codes for
the <command>Delete Message</command> operation.</para>
<table rules="all">
<caption>Descriptions of Delete Message Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>URI has invalid parameters</td>
</tr>
<tr>
<td>204</td>
<td>Success</td>
</tr>
<tr>
<td>204</td>
<td>Delete message from a non-existing queue</td>
</tr>
<tr>
<td>204</td>
<td>Delete a non-existing message</td>
</tr>
<tr>
<td>400</td>
<td>Header has missing fields</td>
</tr>
<tr>
<td>401</td>
<td>Header has invalid auth token</td>
</tr>
<tr>
<td>403</td>
<td>Delete with expired claim ID</td>
</tr>
<tr>
<td>403</td>
<td>Delete with non-existing claim ID</td>
</tr>
<tr>
<td>403</td>
<td>Delete claimed message without providing a claim
ID</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json" </td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="claim_Messages_Codes">
<title>Claim Messages</title>
<para>The following table describes the response codes for
the <command>Claim Messages</command> operation.</para>
<table rules="all">
<caption>Descriptions of Claim Messages Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>201</td>
<td>Success</td>
</tr>
<tr>
<td>204</td>
<td>Success (empty queue with no messages to
claim)</td>
</tr>
<tr>
<td>204</td>
<td>Claim message from a non-existing queue</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with invalid value for
<parameter>limit</parameter> (non-integer, or less
than or equal to 0)</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with <parameter>limit</parameter>
greater than 100)</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with no request body</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with no TTL field</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with invalid TTL value (non-integer,
or less than or equal to 0)</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with invalid JSON</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with non-JSON request body</td>
</tr>
<tr>
<td>400</td>
<td>Claim message with missing header fields</td>
</tr>
<tr>
<td>401</td>
<td>Claim message with invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Item not found</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json" </td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="query_Claim_Codes">
<title>Query Claim</title>
<para>The following table describes the response codes for
the <command>Query Claim</command> operation.</para>
<table rules="all">
<caption>Descriptions of Query Claim Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Success</td>
</tr>
<tr>
<td>200</td>
<td>Query claim with invalid URI parameters</td>
</tr>
<tr>
<td>400</td>
<td>Query claim with missing header fields</td>
</tr>
<tr>
<td>401</td>
<td>Query claim with invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Query expired claim</td>
</tr>
<tr>
<td>404</td>
<td>Query claim from a non-existing queue</td>
</tr>
<tr>
<td>404</td>
<td>Query claim with non-existing claim ID</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="update_Claim_Codes">
<title>Update Claim</title>
<para>The following table describes the response codes for
the <command>Update Claim</command> operation.</para>
<table rules="all">
<caption>Descriptions of Update Claim Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Update claim with invalid URI parameters</td>
</tr>
<tr>
<td>204</td>
<td>Success</td>
</tr>
<tr>
<td>400</td>
<td>Update claim with no request body</td>
</tr>
<tr>
<td>400</td>
<td>Update claim with invalid JSON in request body
</td>
</tr>
<tr>
<td>400</td>
<td>Update claim with non-JSON request body</td>
</tr>
<tr>
<td>400</td>
<td>Update claim with missing header fields</td>
</tr>
<tr>
<td>401</td>
<td>Update claim with invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Update expired claim</td>
</tr>
<tr>
<td>404</td>
<td>Update claim on a non-existing queue</td>
</tr>
<tr>
<td>404</td>
<td>Update a non-existing claim</td>
</tr>
<tr>
<td>406</td>
<td>Update claim with content-type !=
application/json-patch</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="release_Claim_Codes">
<title>Release Claim</title>
<para>The following table describes the response codes for
the <command>Release Claim</command> operation.</para>
<table rules="all">
<caption>Descriptions of Release Claim Response
Codes</caption>
<thead>
<tr>
<td>HTTP Response Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>Release claim with invalid URI parameters</td>
</tr>
<tr>
<td>204</td>
<td>Success</td>
</tr>
<tr>
<td>204</td>
<td>Release expired claim</td>
</tr>
<tr>
<td>204</td>
<td>Release a non-existing claim</td>
</tr>
<tr>
<td>400</td>
<td>Release claim with missing header fields</td>
</tr>
<tr>
<td>401</td>
<td>Release claim with invalid auth token</td>
</tr>
<tr>
<td>404</td>
<td>Release claim from a non-existing queue</td>
</tr>
<tr>
<td>406</td>
<td>Header has Accept != "application/json"</td>
</tr>
<tr>
<td>429</td>
<td>Too many requests</td>
</tr>
</tbody>
</table>
</section>
</section>
</section>
</chapter>
<chapter xml:id="API_Operations_dle001"
xmlns="http://docbook.org/ns/docbook" role="api-reference">
<title>API Operations</title>
<para>This chapter describes each of the Message Queuing operations, which are summarized in the
following table.</para>
<section xml:id="homeDocument-operation">
<title>Home Document</title>
<para>The section describes how to get the home document for Message Queuing.</para>
<note>
<para>The home document schema is currently not ratified in
OpenStack and may change.</para>
</note>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#version">
<wadl:method href="getHomeDocument"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="queue-operations-dle001">
<title>Queues</title>
<para>This section describes queue operations that are supported by the Message Queuing
API.</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#queues">
<wadl:method href="listQueues"/>
</wadl:resource>
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#queue"/>
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#metadata"/>
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#stats"/>
</wadl:resources>
</section>
<section xml:id="message-operations-dle001">
<title>Messages</title>
<para>This section describes message operations that are supported by the Message Queuing
API.</para>
<note>
<para>All message-related operations require that Client-ID be
included in the headers. This is to ensure that messages are
not echoed back to the client that posted them unless the
client explicitly requests this. For more information, see
Client-ID in <xref linkend="commonHeaders"/>.</para>
</note>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#messages"/>
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#message"/>
</wadl:resources>
</section>
<section xml:id="claims-operations-dle001">
<title>Claims</title>
<para>This section describes claim operations that are supported by the Message Queuing
API.</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#claims"/>
<wadl:resource href="../wadl/os-zaqar-apiRef.wadl#claim"/>
</wadl:resources>
</section>
</chapter>
<glossary xml:id="glossary_1">
<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>
View Git Blame Copy Permalink