1823 lines
65 KiB
XML
1823 lines
65 KiB
XML
<?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>
|