diff --git a/.gitignore b/.gitignore index f71de5bb9..6a0513d4e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ -*~ +*.bak +*.DS_Store +target/ *.pyc *.dat TAGS diff --git a/doc-test.conf b/doc-test.conf new file mode 100644 index 000000000..1e32a2dba --- /dev/null +++ b/doc-test.conf @@ -0,0 +1,12 @@ +[DEFAULT] + +repo_name = marconi +api_site=True + +file_exception = includewars.xml + + +# These two options need to come as pairs: +#book=api-quick-start +#target_dir=target/docbkx/webhelp/api-quick-start-onepager-external + diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 000000000..79fa9633a --- /dev/null +++ b/doc/README.md @@ -0,0 +1,2 @@ +Message-Queuing +=============== \ No newline at end of file diff --git a/doc/common/common.ent b/doc/common/common.ent new file mode 100644 index 000000000..22a7375c8 --- /dev/null +++ b/doc/common/common.ent @@ -0,0 +1,49 @@ + + +GET'> +PUT'> +POST'> +DELETE'> +PATCH'> + + + + + + + + + + + + + + + + + + + + + '> + + + + + '> + + + + + + '> diff --git a/doc/includewars.xml b/doc/includewars.xml new file mode 100644 index 000000000..bf2393aac --- /dev/null +++ b/doc/includewars.xml @@ -0,0 +1,15 @@ + + includewars + + jar + + false + + + ${project.basedir}/target/docbkx/webhelp + + **.war + + + + diff --git a/doc/marconi-api-ref/os-marconi-apiRef.xml b/doc/marconi-api-ref/os-marconi-apiRef.xml new file mode 100644 index 000000000..1837435b5 --- /dev/null +++ b/doc/marconi-api-ref/os-marconi-apiRef.xml @@ -0,0 +1,1791 @@ + + + + Message Queuing API v1 Reference + Message Queuing API Reference + + + API v1 + Message Queuing + 2014-02-20 + + + + + Copyright details are filled in by the build + system. + + + + This document is intended for software developers interested in developing applications + using the Message Queuing Application Programming Interface (API). + + + + 2014-02-20 + + Initial document for OpenStack incubation. + + + + + + + Preface + 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 () from one simple API. Unlimited queues and messages give Message + Queuing users the flexibility they need to create powerful web applications in the + cloud. + 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. + 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 + GET 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. + 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. +
+ Intended Audience + 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: + + + RESTful web services + + + HTTP/1.1 conventions + + + JSON data serialization formats + + +
+
+ Document Change History + This version of the document replaces and obsoletes all + earlier versions. The most recent changes are described in the + following table. + +
+ + + + + Concepts + To use the Message Queueing API effectively, you should + understand the key concepts described in this section. +
+ How Message Queuing Works + Following is an overview of how Message Queuing works. For definitions of Message + Queuing terms, see the . + + + You create a queue to which producers or publishers + post messages. + + + Workers (consumers or subscribers) claim or get a + message from the queue, complete the work in that message, + and delete the message. + 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. + + + Subscribers monitor the claims from these queues to + track activity and help troubleshoot errors. + + + 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. +
+
+ Messaging Patterns + The Message Queuing API supports a variety of messaging patterns including the + following: + + + producer-consumer + + + publish-subscribe + + +
+ Producer-Consumer + The producer-consumer pattern has the following + characteristics: + + + A producer is programmed to send messages to a + queue. + + + Multiple workers (or consumers) are programmed to + monitor a queue. + + + Only one worker can claim a message so that no other + worker can claim the message and duplicate the + work. + + + The worker must delete the message when work is + done. + + + TTL restores a message to an unclaimed state if the + worker never finishes. + + + This pattern is ideal for dispatching jobs to multiple + processors. +
+
+ Publish-Subscribe + Characteristics of the Publish-Subscribe pattern + are: + + + The publisher sends a message to a queue. + + + All workers (or subscribers) listen to the messages + in the queue. + + + Workers do not claim a message. + + + Multiple workers can take action on a + message. + + + Workers can send a marker or cursor to skip messages + already seen. + + + TTL eventually deletes messages. + + + This pattern is ideal for notification of events to + multiple workers at once. +
+
+
+ Use Cases + Queuing systems are used to coordinate tasks within an + application. Here are some examples: + + + Backup: 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. + + + Storage: 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. + + + Email: 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. + + + Following are some generic use cases for Message Queuing: + + + Distribute tasks among multiple workers (transactional + job queues) + + + Forward events to data collectors (transactional event + queues) + + + Publish events to any number of subscribers + (publish-subscribe) + + + Send commands to one or more agents (point-to-point or + publish-subscribe) + + + Request an action or get information from a Remote + Procedure Call (RPC) agent + + +
+ + + General API Information + 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. + + All requests to authenticate against and operate the + service are performed using SSL over HTTP (HTTPS) on TCP port + 443. + +
+ Authentication + You can use cURL to try the authentication process in two steps: + get a token, and send the token to a service. + + Get an authentication token by providing your user + name and either your API key or your password. Here are + examples of both approaches: + You can request a token by providing your user name + and your password. + $ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json' + 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 X-Auth-Token header. + Authentication also returns a service catalog, + listing the endpoints you can use for Cloud + services. + + + Use the authentication token to send a + GET to a service you would like to + use. + + + 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. + + 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. + +
+
+ Request and Response Types + The Message Queuing API supports JSON data serialization formats. You specify the + request format by using the Content-Type header. The request format is + required 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 + .json extension to the request URI. JSON is also used for the response + format. + + + + + + + + + + + + + + + + + + + +
Response Format
FormatAccept HeaderQuery ExtensionDefault
JSONapplication/json.jsonYes
+
+ +
+ Absolute Limits + Accounts are configured with default thresholds, or limits, that manage capacity and + prevent abuse of the system. + The following table provides details about the absolute limits for the Message Queuing + API. + + These limits are configurable. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Absolute Limits
TypeDescriptionLimitDefault
Limits on Messages and Queues per RequestNumber of queue records per page of results when listing queues1 - 100020
Number of messages per page of results when listing messages1 - 2520
Number of messages that can be posted in a single request1 - 2520
Number of messages that can be claimed at one time1 - 2520
Number of messages that can be deleted in a single bulk delete request1 - 2520
Number of messages that can be requested in a bulk get by ID1 - 2520
Time LimitsValid range for a message TTL60 - 1209600 seconds (1 minute to 14 days)1209600 seconds
Valid range for a claim TTL60 - 43200 seconds (1 minute to 12 hours)43200 seconds
Valid range for claim grace period60 - 43200 seconds (1 minute to 12 hours)43200 seconds
Data LimitsQueue metadata JSONCannot exceed 262144 bytes, including whitespace (256 KB)65536 bytes
Message body JSONCannot exceed 262144 bytes, including whitespace (256 KB)262144 bytes
+ + 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. + +
+
+ Common Headers + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Common Headers
HeaderDescription
HostHost name of the API
DateCurrent date and time
AcceptMedia type desired; initially, only + application/json is supported. Note: The Accept header is + required. +
Accept-EncodingSpecifies that the agent accepts gzip-encoded response + bodies
Content-Typeapplication/json +
Content-LengthFor POST or PUT + requests, the length in bytes of the message document + being submitted
X-Auth-TokenAuth token
X-Project-IdAn ID for a project to which the value of X-Auth-Token + grants access. Queues are created under this + project.
Client-IDA UUID for each client instance. The UUID must be + submitted in its canonical form (for example, + 3381af92-2b9e-11e3-b191-71861300734c). The client + generates the Client-ID once. Client-ID persists between + restarts of the client so the client should reuse that + same Client-ID. Note: All + message-related operations require the use of + Client-ID in the headers to ensure that + messages are not echoed back to the client that posted + them, unless the client explicitly requests + this.
+
+
+ Date and Time Format + For the display and consumption of date and time values, the Message Queuing service + uses a date format that complies with ISO 8601. + + Service Date and Time Format + yyyy-MM-dd'T'HH:mm:ss.SSSZ + For example, May 19, 2013 at 8:07:08 A.M., GMT-5 would + have the following format: + 2013-05-19T08:07:08-05:00 + + The following table describes the date and time format + codes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Explanation of Date and Time Format Codes
CodeDescription
yyyyFour-digit year
MMTwo-digit month
ddTwo-digit day of at the month
TSeparator for date and time
HHTwo-digit hour of the day (00-23)
mmTwo-digit minutes of the hour
ssTwo-digit seconds of the minute
SSSThree-digit milliseconds of the second
ZRFC 822 time zone
+
+
+ Faults + If any Message Queuing request results in an error, the queuing service returns an + appropriate 4xx or 5xx + HTTP status code, and the following information in the body: + + + Title + + + Description + + + Internal code + + + Link to more information + + + An example of an error message + follows. + + Error Message Example + 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" + } +} + + Detailed error information for each API operation is + included in the following sections. Additionally, brief error + information is included in each operation description in . +
+ Response Codes and Explanations + This section includes response codes and explanations for each of the Message Queuing + API operations. The operations are described in . +
+ Create Queue + The following table describes the response codes for + the Create Queue operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Create Queue Response + Codes
HTTP Response CodeDescription
201Success (created)
204Success (already exists)
400Queue has a long name (greater than 64 bytes)
400Request header has missing fields
401Request header has invalid auth token
429Too many requests
+
+
+ List Queues + The following table describes the response codes for + the List Queues operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of List Queues Response + Codes
HTTP Response CodeDescription
200Success
200URI has invalid parameter (something other than + limit, + marker, or + metadata)
204Request with non-existing value for + marker
400Request with negative value for + limit
400Request with zero value for + limit
400Request with non-boolean value for + metadata
400Header has missing fields
401Request header has invalid auth token
404Request a non-existing queue
406Header has Accept != "application/json"
429Too many requests
+
+
+ Delete Queue + The following table describes the response codes for + the Delete Queue operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Delete Queue Response + Codes
HTTP Response CodeDescription
200URI has invalid parameters
204Success
204Delete a non-existing queue
400Header has missing fields
401Request header has invalid auth token
406Header has Accept != "application/json"
429Too many requests
+
+
+ Check Queue Existence + The following table describes the response codes for + the Check Queue Existence + operation. + + + + + + + + + + + + + + + + + + +
Descriptions of Check Queue Existence Response + Codes
HTTP Response CodeDescription
204Check a non-existing queue
404Request a non-existing queue
+
+
+ Set Queue Metadata + The following table describes the response codes for + the Set Queue Metadata + operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Set Queue Metadata Response + Codes
HTTP Response CodeDescription
204Success
400Request body is empty
400Request body is greater than 64 KB
400Request body has malformed JSON
400Request with non-JSON body
406Request header has Accept != + "application/json"
429Too many requests
+ Request with UTF-16 char JSON body
+
+
+ Get Queue Metadata + The following table describes the response codes for + the Get Queue Metadata + operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Get Queue Metadata Response + Codes
HTTP Response CodeDescription
200Success
200No metadata exists for the queue
200URI has invalid parameters
400Header has missing fields
401Request header has invalid auth token
404Request metadata for a non-existing queue
406Header has Accept != "application/json"
429Too many requests
+
+
+ Get Queue Stats + The following table describes the response codes for + the Get Queue Stats operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Get Queue Stats Response + Codes
HTTP Response CodeDescription
200Success
200URI has invalid parameters
400Header has missing fields
401Request header has invalid auth token
404Request stats for a non-existing queue
406Header has Accept != "application/json"
429Too many requests
+
+
+ Post Message + The following table describes the response codes for + the Post Message operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Post Message Response + Codes
HTTP Response CodeDescription
200URI has invalid parameters
201Success
201Post multiple messages in a single request, few of + them succeed (with "partial": + true)
400Post greater than 100 messages with a single + request
400Post with request body greater than 4 KB
400Post with invalid JSON request body
400Post with non-JSON request body
400Post with non-JSON message
400Post with TTL less than 60
400Post with TTL greater than 1209600
400Post with non-integer value of TTL
400Post with negative value of TTL
400Post without TTL in request body
400Post without "body" in + request body
400Post with no request body
400Post with messages encapsulated in multiple + arrays
400Header has missing fields
401Header has invalid auth token
404Post message to a non-existing queue
406Header has Accept != "application/json"
429Too many requests
503Post multiple messages in a single request and all + of them fail
+
+
+ Get Messages + The following table describes the response codes for + the Get Messages operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Get Messages Response + Codes
HTTP Response CodeDescription
200Success (query matched 1 or more messages)
200Request message with invalid parameter (something + other than marker, + limit, or + echo)
204Success (query has no match)
204Request message with non-existing + marker +
400Request message with limit greater than 100
400Post with request body greater than 4 KB
400Request message with limit less than or equal to 0 +
400Request message with non-boolean value for + echo +
401Header has invalid auth token
404Request message from a non-existing queue
406Header has Accept != "application/json"
429Too many requests
+
+
+ Get a Set of Messages by ID + The following table describes the response codes for + the Get a Set of Messages by ID + operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Get a Set of Messages by ID + Response Codes
HTTP Response CodeDescription
200Success
200URI has invalid parameters
400Request message with limit greater than 100
401Post with request body greater than 4 KB
404Request message with limit less than or equal to 0 +
404Request message with non-boolean value for + echo +
406Header has invalid auth token
429Too many requests
+
+
+ Delete a Set of Messages by ID + The following table describes the response codes for + the Delete a Set of Messages by ID + operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Delete a Set of Messages by ID + Response Codes
HTTP Response CodeDescription
204Success
204Delete message from a non-existing queue
204Delete a non-existing message
400Header has missing fields
401Header has invalid auth token
403Delete with expired claim ID
403Delete with non-existing claim ID
403Delete claimed message without providing a claim + ID
406Header has Accept != "application/json"
429Too many requests
+
+
+ Get a Specific Message + The following table describes the response codes for + the Get a Specific Message + operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Get a Specific Message Response + Codes
HTTP Response CodeDescription
200Success(query matched the message)
200URI has invalid parameters
400Header has missing fields
401Header has invalid auth token
404Request message from a non-existing queue
404Request a non-existing message
404Request an expired message
406Header has Accept != "application/json"
429Too many requests
+
+
+ Delete Message + The following table describes the response codes for + the Delete Message operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Delete Message Response + Codes
HTTP Response CodeDescription
200URI has invalid parameters
204Success
204Delete message from a non-existing queue
204Delete a non-existing message
400Header has missing fields
401Header has invalid auth token
403Delete with expired claim ID
403Delete with non-existing claim ID
403Delete claimed message without providing a claim + ID
406Header has Accept != "application/json"
429Too many requests
+
+
+ Claim Messages + The following table describes the response codes for + the Claim Messages operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Claim Messages Response + Codes
HTTP Response CodeDescription
201Success
204Success (empty queue with no messages to + claim)
204Claim message from a non-existing queue
400Claim message with invalid value for + limit (non-integer, or less + than or equal to 0)
400Claim message with limit + greater than 100)
400Claim message with no request body
400Claim message with no TTL field
400Claim message with invalid TTL value (non-integer, + or less than or equal to 0)
400Claim message with invalid JSON
400Claim message with non-JSON request body
400Claim message with missing header fields
401Claim message with invalid auth token
404Item not found
406Header has Accept != "application/json"
429Too many requests
+
+
+ Query Claim + The following table describes the response codes for + the Query Claim operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Query Claim Response + Codes
HTTP Response CodeDescription
200Success
200Query claim with invalid URI parameters
400Query claim with missing header fields
401Query claim with invalid auth token
404Query expired claim
404Query claim from a non-existing queue
404Query claim with non-existing claim ID
406Header has Accept != "application/json"
429Too many requests
+
+
+ Update Claim + The following table describes the response codes for + the Update Claim operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Update Claim Response + Codes
HTTP Response CodeDescription
200Update claim with invalid URI parameters
204Success
400Update claim with no request body
400Update claim with invalid JSON in request body +
400Update claim with non-JSON request body
400Update claim with missing header fields
401Update claim with invalid auth token
404Update expired claim
404Update claim on a non-existing queue
404Update a non-existing claim
406Update claim with content-type != + application/json-patch
429Too many requests
+
+
+ Release Claim + The following table describes the response codes for + the Release Claim operation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Descriptions of Release Claim Response + Codes
HTTP Response CodeDescription
200Release claim with invalid URI parameters
204Success
204Release expired claim
204Release a non-existing claim
400Release claim with missing header fields
401Release claim with invalid auth token
404Release claim from a non-existing queue
406Header has Accept != "application/json"
429Too many requests
+
+
+
+ + + API Operations + This chapter describes each of the Message Queuing operations, which are summarized in the + following table. +
+ Home Document + The section describes how to get the home document for Message Queuing. + + The home document schema is currently not ratified in + OpenStack and may change. + + + + + + +
+
+ Queues + This section describes queue operations that are supported by the Message Queuing + API. + + + + + + + + +
+
+ Messages + This section describes message operations that are supported by the Message Queuing + API. + + 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 . + + + + + +
+
+ Claims + This section describes claim operations that are supported by the Message Queuing + API. + + + + +
+ + + Glossary + + Claim + + 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. + + + + Claim TTL + + Defines how long a message will be in claimed state. A + message can be claimed by one worker at a time. + + + + Consumer + + A server that claims messages from the queue. + + + + Message + + 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. + + + + Message TTL + + Defines how long a message will be accessible. + + + + Producer + + A server or application that sends messages to the + queue. + + + + Producer - Consumer + + 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. + + + + Publisher + + A server or application that posts messages to the queue + with the intent to distribute information or updates to + multiple subscribers. + + + + Publisher - Subscriber + + A pattern where all worker applications have access to + all messages in the queue. Workers cannot delete or update + messages. + + + + Queue + + 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. + + + + Subscriber + + An observer that watches messages like an RSS feed but + does not claim any messages. + + + + TTL + + Time-to-live value. + + + + Worker + + A client that claims messages from the queue and + performs actions based on those messages. + + + + diff --git a/doc/marconi-api-ref/pom.xml b/doc/marconi-api-ref/pom.xml new file mode 100644 index 000000000..8e95d721a --- /dev/null +++ b/doc/marconi-api-ref/pom.xml @@ -0,0 +1,67 @@ + + + org.openstack.docs + parent-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + marconi-api-ref + jar + Message Queuing API v1 Reference + + + local + 1 + + + + + com.rackspace.cloud.api + clouddocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + os-marconi-apiRef.xml + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + chapter toc,title + section toc + part toc,title + qandadiv toc + qandaset toc + reference toc,title + set toc,title + marconi-api-ref + marconi-api-ref + + + + + 1 + 0 + builtforOpenStack + true + 1 + 0 + 1 + 0 + false + true + . + http://docs.openstack.org/marconi-api-ref/content/ + + + + + diff --git a/doc/marconi-get-started/os-marconi-apiGettingStarted.xml b/doc/marconi-get-started/os-marconi-apiGettingStarted.xml new file mode 100644 index 000000000..82f81ceee --- /dev/null +++ b/doc/marconi-get-started/os-marconi-apiGettingStarted.xml @@ -0,0 +1,1110 @@ + + + + + + +GET'> +PUT'> +POST'> +DELETE'> + + + + + + '> + + + + + '> +]> + + Message Queuing API v1 Getting Started Guide + Message Queuing Getting Started Guide + + + + + + + + + + API v1 + Message Queuing + 2014-02-20 + + + + Copyright details are filled in by the build + system. + + + + This document is intended for software developers interested in developing + applications using the Message Queuing Application Programming Interface + (API). + + + + 2014-02-20 + + Initial document for OpenStack incubation + incubation. + + + + + + Document Change History + This version of the document replaces and obsoletes all + earlier versions. The most recent changes are described in + the following table: + + + + Overview + Message Queuing is a RESTful API-based messaging service that supports distributed web + applications. A message service such as Message Queuing is a vital component of large, + distributed web applications. You can use Message Queuing for public, private, and + hybrid cloud environments. + As you develop distributed web applications, you often have multiple agents set up to + complete sets of tasks for those applications. These tasks can be anything from creating + users to deleting blocks of storage. Message Queuing provides a simple interface to + create these tasks as queues, messages, and claims and to post, claim, read, and delete + them as the tasks are needed and performed. + Message Queuing handles the distribution of tasks, but it does not necessarily manage + the order of the tasks. Applications handle the workflow at a higher level. + Message Queuing is based on the OpenStack Marconi project. + This guide explains how to access and start using the API so that you can begin to use + Message Queuing for your applications. Instructions are given for how to properly enter + the necessary URLs, using cURL, to set up and use a basic set of Message Queuing + operations. +
+ Prerequisites for Running Examples + In + order to run the examples in this guide, you must have + the following prerequisites: + + + An Cloud account + + + An username and password, as + specified during registration + + + Prior knowledge of HTTP/1.1 + conventions + + + Basic familiarity with Cloud and RESTful + APIs + + +
+
+ How Message Queuing Works + Following is an overview of how Message Queuing works. For definitions of Message + Queuing terms, see the . + + + You create a queue to which producers or + publishers post messages. + + + Workers (consumers or subscribers) claim or + get a message from the queue, complete the + work in that message, and delete the + message. + 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. + + + Subscribers monitor the claims from these + queues to track activity and help troubleshoot + errors. + + + 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. +
+ Messaging Patterns + Message Queuing supports a variety of messaging patterns including the + following: + + + producer-consumer + + + publish-subscribe + + +
+ Producer-Consumer + The producer-consumer pattern has the + following characteristics: + + + A producer is programmed to send + messages to a queue. + + + Multiple workers (or consumers) are + programmed to monitor a queue. + + + Only one worker can claim a message + so that no other worker can claim the + message and duplicate the work. + + + The worker must delete the message + when work is done. + + + TTL restores a message to an + unclaimed state if the worker never + finishes. + + + This pattern is ideal for dispatching jobs + to multiple processors. +
+
+ Publish-Subscribe + Characteristics of the Publish-Subscribe + pattern are: + + + The publisher sends a message to a + queue. + + + All workers (or subscribers) listen + to the messages in the queue. + + + Workers do not claim a + message. + + + Multiple workers can take action on + a message. + + + Workers can send a marker or cursor + to skip messages already seen. + + + TTL eventually deletes + messages. + + + This pattern is ideal for notification of + events to multiple workers at once. +
+
+
+ Message Queuing Operations + This section lists all of the operations that are available in the Message + Queuing API. This document uses some of the most common operations in . + For details about all of the operations, see the Message Queuing + API v1 Reference. +
+ Home Document + The following operation is available for the + home document: + + + Get Home Document + + +
+
+ Queues + The following operations are available for + queues: + + + Create Queue + + + List Queues + + + Check Queue Existence + + + Set Queue Metadata + + + Get Queue Metadata + + + Get Queue Stats + + + Delete Queue + + +
+
+ Messages + The following operations are available for + messages: + + + Post Message + + + Get Messages + + + Get a Specific Message + + + Get a Set of Messages by ID + + + Delete Message + + + Delete a Set of Messages by + ID + + +
+
+ Claims + The following operations are available for + claims: + + + Claim Messages + + + Query Claim + + + Update Claim + + + Release Claim + + +
+
+
+ Use Cases + Queuing systems are used to coordinate tasks + within an application. Here are some + examples: + + + Backup: + 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. + + + Storage: 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. + + + Email: + 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. + + + + Following are some generic use cases for Message Queuing: + + + Distribute tasks among multiple workers + (transactional job queues) + + + Forward events to data collectors + (transactional event queues) + + + Publish events to any number of + subscribers (publish-subscribe) + + + Send commands to one or more agents + (point-to-point or + publish-subscribe) + + + Request an action or get information + from a Remote Procedure Call (RPC) + agent + + +
+
+ + + Send Requests to the API + You have several options for sending requests through an + API: + + + Developers and testers may prefer to use cURL, + the command-line tool from http://curl.haxx.se/. + With cURL you can send HTTP requests and receive + responses back from the command line. + + + If you like to use a more graphical interface, + the REST client for Firefox also works well for + testing and trying out commands, see https://addons.mozilla.org/en-US/firefox/addon/restclient/. + + + + You can also download and install rest-client, a + Java application to test RESTful web services, + from http://code.google.com/p/rest-client/. + + + +
+ Sending API Requests Using cURL + cURL is a command-line tool that is available in + UNIX® system-based environments and Apple Mac OS X® + systems, and can be downloaded for Microsoft Windows® + to interact with the REST interfaces. For more + information about cURL, visit http://curl.haxx.se/. + cURL enables you to transmit and receive HTTP + requests and responses from the command line or from + within a shell script. As a result, you can work with + the REST API directly without using one of the client + APIs. + The following cURL command-line options are used in + this guide to run the examples. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cURL Command-Line Options
OptionDescription
-dSends the specified data in a + POST request to the HTTP + server.
-iIncludes the HTTP header in the + output.
-H HEADERSpecifies an HTTP header in the + request.
-XSpecifies the request method to use when + communicating with the HTTP server. The + specified request is used instead of the + default method, which is GET. For example, + -X PUT specifies to use + the PUT request method.
+ + If you have the tools, you can run the cURL JSON + request examples with the following options to + format the output from cURL: <curl + JSON request example> | python + -mjson.tool. + +
+
+ Copying and Pasting cURL Request Examples into a + Terminal Window + To run the cURL request examples shown in this guide + () on + Linux or Mac systems, perform the following + actions: + + + Copy and paste each example from the HTML + version of this guide into an ASCII text + editor (for example, vi or TextEdit). You can + click on the small document icon to the right + of each request example to select it. + + + Modify each example with your required + account information and so forth, as detailed + in this guide. + + + After you are finished modifying the text + for the cURL request example with your + information (for example,your_username + and your_api_key), + paste it into your terminal window. + + + Press Enter to run the + cURL command. + + + + The carriage returns in the cURL request + examples that are part of the cURL syntax are + escaped with a backslash (\) in order to avoid + prematurely terminating the command. However, you + should not escape carriage returns inside the JSON + message within the command. + + + If you have trouble copying and pasting the + examples as described, try typing the entire + example on one long line, removing all the + backslash line continuation characters. + +
+ + + Generate an Authentication Token + You can use cURL to try the + authentication process in two steps: get a token, and send the token to a service. + + Get an authentication token by providing your user name and either your + API key or your password. Here are examples of both approaches: + You can request a token by providing your user name and your + password. + $ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json' + 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 X-Auth-Token header. + Authentication also returns a service catalog, listing the endpoints you + can use for Cloud services. + + + Use the authentication token to send a GET to a service + you would like to use. + + + 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. + + 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. + + + + Common Headers + Each request to the Message Queuing API must include certain standard and extended + HTTP headers (as shown in the following table). These headers provide host, agent, + authentication, and other pertinent information to the server. The following table + provides the common headers used by the API. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Common Headers
HeaderDescription
HostHost name of the API
DateCurrent date and time
AcceptMedia type to use. Initially, only + application/json is + supported. Note: The + Accept header is + required.
Accept-EncodingSpecifies that the agent accepts gzip-encoded + response bodies
Content-Typeapplication/json
Content-LengthFor POST or + PUT requests, the + length in bytes of the message document being + submitted
X-Auth-TokenAuthorization token
X-Project-IdAn ID for a project to which the value of + X-Auth-Token grants access. Queues are created + under this project. The project ID is the same + as the account ID (also sometimes called + tenant ID).
Client-IDA UUID for each client instance. The UUID must + be submitted in its canonical form (for + example, + 3381af92-2b9e-11e3-b191-71861300734c). The + client generates the Client-ID once. Client-ID + persists between restarts of the client so the + client should reuse that same Client-ID. + Note: All + message-related operations require the use + of Client-ID in the headers + to ensure that messages are not echoed + back to the client that posted them, + unless the client explicitly requests + this.
+ + + Working with the Message Queuing API + This chapter contains a simple exercise with some basic Message Queuing requests that + you will commonly use. Example requests are provided in cURL, followed by the + response. + For a complete list of operations available for Message Queuing, see . Each operation is fully described in the + Message Queuing API v1 Reference. +
+ Create Queue + The Create Queue operation creates a queue in the + region of your choice. + The body of the PUT request is empty. + The template is as follows: + + PUT {endpoint}/queues/{queue_name} + + The queue_name parameter + specifies the name to give the queue. The name + must not exceed + 64 bytes in length and is limited to US-ASCII letters, + digits, underscores, and hyphens. + Following are examples of a Create Queue request and + response: + + cURL Create Queue Request + curl -i -X PUT https://queues.api.openstack.org/v1/queues/samplequeue \ +-H "X-Auth-Token: your_auth_token" \ +-H "Accept: application/json" \ +-H "X-Project-Id: your_project_ID" + + + Create Queue Response + HTTP/1.1 201 Created +Content-Length: 0 +Location: /v1/queues/samplequeue + +
+
+ Post Message + The Post Message operation inserts one or more + messages in a queue. + You can submit up to 10 messages in a single + request, but you must encapsulate them in a collection + container (an array in JSON, even for a single message + - without the JSON array, you receive an "Invalid body + request" error message). You can use the resulting + value of the location header or response body to + retrieve the created messages for further processing + if needed. + The template is as + follows:POST {endpoint}/queues/{queue_name}/messages + The client specifies only the body and ttl + attributes for the message. Metadata, such as id and age, is added. + The response body contains a list of resource paths + that correspond to each message submitted in the + request, in the same order as they were submitted. If + a server-side error occurs during the processing of + the submitted messages, a partial list is returned. + The partial attribute is set to + true, and the client tries + to post the remaining messages again. The + body attribute specifies an + arbitrary document that constitutes the body of the + message being sent. + The following rules apply for the maximum size: + + The size is limited to 256 KB for the + entire request body (as-is), including + whitespace. + + + The maximum size of posted messages is + the maximum size of the entire request + document (rather than the sum of the + individual message body field + values as it was earlier releases). On + error, the client is notified of by how + much the request exceeded the + limit. + + + + The document must be valid JSON. (The Message + Queuing service validates it.) + The ttl attribute specifies + the lifetime of the message. When the lifetime + expires, the server deletes the message and removes it + from the queue. Valid values are 60 through 1209600 + seconds (14 days). + + The server might not actually delete the + message until its age reaches (ttl + 60) seconds. So + there might be a delay of 60 seconds after the + message expires before it is deleted. + + The following are examples of a Post Message request + and response: + + cURL Post Message Request + curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/messages -d \ +'[{"ttl": 300,"body": {"event": "BackupStarted"}},{"ttl": 60,"body": {"play": "hockey"}}]' \ +-H "Content-type: application/json" \ +-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \ +-H "X-Auth-Token: your_auth_token" \ +-H "Accept: application/json" \ +-H "X-Project-Id: your_project_ID" + + + Post Message Response + HTTP/1.1 201 Created +Content-Length: 153 +Content-Type: application/json; charset=utf-8 +Location: /v1/queues/samplequeue/messages?ids=51ca00a0c508f154c912b85c,51ca00a0c508f154c912b85d + +{"partial": false, "resources": ["/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c", "/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85d"]} + + +
+
+ Claim Messages + The Claim Messages operation claims a set of messages (up to the value of the + limit parameter) from oldest to newest and skips any + messages that are already claimed. If there are no messages available to claim, the + Message Queuing service returns an HTTP 204 No Content response + code. + The template is as follows: + POST {endpoint}/queues/{queue_name}/claims{?limit} +Content-Type: application/json + +{ + "ttl": {claim_ttl}, + "grace": {message_grace} +} + The client (worker) needs to delete the message when it has finished processing + it. The client deletes the message before the claim expires to ensure that the + message is processed only once. If a client needs more time, the Cloud Service + provides the Update Claim operation to make changes. See the Message + Queuing API v1 Reference for a description of this operation. As + part of the delete operation, workers specify the claim ID (which is best done by + simply using the provided href). If workers perform these actions, then if a claim + simply expires, the server can return an error and notify the worker of a possible + race condition. This action gives the worker a chance to roll back its own + processing of the given message because another worker can claim the message and + process it. + The age given for a claim is relative to the + server's clock. The claim's age is useful for + determining how quickly messages are getting processed + and whether a given message's claim is about to + expire. + When a claim expires, it is released back to the + queue for other workers to claim. (If the original + worker failed to process the message, another client + worker can then claim the message.) + The limit parameter specifies + the number of messages to claim. The limit parameter is configurable. + The default is 20. Messages + are claimed based on the number of messages available. + The server might claim and return less than the + requested number of messages. + The ttl attribute specifies + the lifetime of the claim. While messages are claimed, + they are not available to other workers. The value + must be between 60 and 43200 seconds (12 + hours). + The grace attribute specifies + the message grace period in seconds. Valid values are + between 60 and 43200 seconds (12 hours). To deal with + workers that have stopped responding (for up to + 1209600 seconds or 14 days, including claim lifetime), + the server extends the lifetime of claimed messages to + be at least as long as the lifetime of the claim + itself, plus the specified grace period. If a claimed + message normally lives longer than the grace period, + its expiration is not adjusted. it + Following are examples of a Claim Messages request + and response: + + cURL Claim Messages Request + curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/claims -d \ +'{"ttl": 300,"grace":300}' \ +-H "Content-type: application/json" \ +-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \ +-H "X-Auth-Token: your_auth_token" \ +-H "Accept: application/json" \ +-H "X-Project-Id: your_project_ID" + + + Claim Messages Response + HTTP/1.1 201 OK +Content-Length: 164 +Content-Type: application/json; charset=utf-8 +Location: /v1/queues/samplequeue/claims/51ca011c821e7250f344efd6 +X-Project-Id: your_project_ID + +[ + { + "body": { + "event": "BackupStarted" + }, + "age": 124, + "href": "\/v1\/queues\/samplequeue\/messages\/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6", + "ttl": 300 + } +] + +
+
+ Delete Message with Claim ID + The Delete Message operations deletes + messages. + The template is as + follows:DELETE {endpoint}/queues/{queue_name}/messages/{message_id}{?claim_id} + + The message_id parameter + specifies the message to delete. + The claim_id parameter + specifies that the message is deleted only if it has + the specified claim ID and that claim has not expired. + This specification is useful for ensuring that only + one worker processes any given message. When a + worker's claim expires before it deletes a message + that it has processed, the worker must roll back any + actions it took based on that message because another + worker can now claim and process the same + message. + Following are examples of a Delete Message request + and response: + + cURL Delete Message Request + curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6 \ +-H "Content-type: application/json" \ +-H "X-Auth-Token: your_auth_token" \ +-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \ +-H "Accept: application/json" \ +-H "X-Project-Id: your_project_ID" + + + Delete Message Response + HTTP/1.1 204 No Content + +
+
+ Release Claim + The Release Claim operation immediately releases a + claim, making any remaining, undeleted) messages + associated with the claim available to other + workers. + The template is as follows: + DELETE {endpoint}/queues/{queue_name}/claims/{claim_id} + This operation is useful when a worker is performing + a graceful shutdown, fails to process one or more + messages, or is taking longer than expected to process + messages and wants to make the remainder of the + messages available to other workers. + Following are examples of a Release Claim request + and response: + + cURL Release Claim Request + curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/claims/51ca011c821e7250f344efd6 \ +-H "Content-type: application/json" \ +-H "X-Auth-Token: your_auth_token" \ +-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \ +-H "Accept: application/json" \ +-H "X-Project-Id: your_project_ID" + + + Release Claim Response + HTTP/1.1 204 No Content + +
+
+ Delete Queue + The Delete Queue operation immediately deletes a + queue and all of its existing messages. + The template is as + follows:DELETE {endpoint}/queues/{queue_name} + Following are examples of a Delete Queue request and + response: + + cURL Delete Queue Request + curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue \ +-H "Content-type: application/json" \ +-H "X-Auth-Token: your_auth_token" \ +-H "Accept: application/json" \ +-H "X-Project-Id: your_project_ID" + + + Delete Queue Response + HTTP/1.1 204 No Content + + +
+ + + Additional Resources + For more information about using the API, see the Message Queuing API v1 + Reference. All you need to get started with Message Queuing is the + getting started guide, the reference, and your Cloud account. + For information about the OpenStack Marconi API, see + wiki.openstack.org/wiki/Marconi/specs/api/v1. + This API uses standard HTTP 1.1 response codes as + documented at www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. + + + + Glossary + + Claim + + 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. + + + + Claim TTL + + Defines how long a message will be in claimed + state. A message can be claimed by one worker at a + time. + + + + Consumer + + A server that claims messages from the + queue. + + + + Message + + 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. + + + + Message TTL + + Defines how long a message will be accessible. + + + + + Producer + + A server or application that sends messages to + the queue. + + + + Producer - Consumer + + 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. + + + + Publisher + + A server or application that posts messages to + the queue with the intent to distribute + information or updates to multiple + subscribers. + + + + Publisher - Subscriber + + A pattern where all worker applications have + access to all messages in the queue. Workers + cannot delete or update messages. + + + + Queue + + 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. + + + + Subscriber + + An observer that watches messages like an RSS + feed but does not claim any messages. + + + + TTL + + Time-to-live value. + + + + Worker + + A client that claims messages from the queue and + performs actions based on those messages. + + + + diff --git a/doc/marconi-get-started/pom.xml b/doc/marconi-get-started/pom.xml new file mode 100644 index 000000000..45bd9f41f --- /dev/null +++ b/doc/marconi-get-started/pom.xml @@ -0,0 +1,68 @@ + + + org.openstack.docs + parent-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + marconi-get-started + jar + Message Queuing API v1 Getting Started + + + local + 1 + + + + + com.rackspace.cloud.api + clouddocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + + os-marconi-apiGettingStarted.xml + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + chapter toc,title + section toc + part toc,title + qandadiv toc + qandaset to + reference toc,title + set toc,title + marconi-get-started + marconi-get-started + + + + + 1 + 0 + builtforOpenStack + true + 1 + 0 + 1 + 0 + false + true + . + http://docs.openstack.org/marconi-getting-started/content/ + + + + + diff --git a/doc/pom.xml b/doc/pom.xml new file mode 100644 index 000000000..b5350a368 --- /dev/null +++ b/doc/pom.xml @@ -0,0 +1,44 @@ + + 4.0.0 + org.openstack.docs + parent-pom + 1.0.0-SNAPSHOT + pom + + marconi-api-ref + marconi-get-started + + + + Rackspace Research Repositories + + true + + + + rackspace-research + Rackspace Research Repository + http://maven.research.rackspacecloud.com/content/groups/public/ + + + + + rackspace-research + Rackspace Research Repository + http://maven.research.rackspacecloud.com/content/groups/public/ + + + + + + + + com.rackspace.cloud.api + clouddocs-maven-plugin + 1.13.0 + + + + diff --git a/doc/wadl/os-marconi-apiRef.wadl b/doc/wadl/os-marconi-apiRef.wadl new file mode 100644 index 000000000..6ff504113 --- /dev/null +++ b/doc/wadl/os-marconi-apiRef.wadl @@ -0,0 +1,691 @@ + + + + %common; +]> + + + + + + + + + + + + + + + + + + + + Specifies the name of the queue. + + + + + + + + + + + + + + + + + + Specifies the message ID. + + + + + + + + + Specifies the claim ID. + + + + + + + + + + + + + + + + + + + + + Gets the home document. + This operation gets the home document. + The entire API is discoverable from a single starting point, the home document. To explore the entire API, you need to know only this one URI. This document is cacheable. + The home document lets you write clients by using relational links, so clients do not have to construct their own URLs. You can click through and view the JSON doc in your browser. + For more information about home documents, see http://tools.ietf.org/html/draft-nottingham-json-home-02. + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a queue. + This operation creates a new queue. + The body of the request is empty. + queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. + + + + + + + + + + + + + + + + + &commonFaults; + + + + + + + + + Lists queues. + A request to list queues when you have no queues in your account returns 204, instead of 200, because there was no information to send back. + This operation lists queues for the project. The queues are sorted alphabetically by name. + + + + + Specifies the name of the last queue received in a previous request, or none to get the first page of results. + + + + + Specifies the number of queues to return. The default value for the number of queues returned is 10. If you do not specify this parameter, the default number of queues is returned. + + + + + Determines whether queue metadata is included in the response. The default value for this parameter is false, which excludes the metadata. + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + + Sets metadata for the specified queue. + This operation sets metadata for the specified queue. + The request body has a limit of 256 KB, including whitespace (when re-serialized as JSON). + This operation replaces any existing metadata document in its entirety. Ensure that you do not accidentally overwrite existing metadata that you want to retain. + The body of the request includes contextual information about the way a particular application interacts with the queue. The document must be valid JSON. (The Message Queuing service validates it.) + queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. + + + + + + + + + + + + + + + + + + &commonFaults; + + + + + + + + + Returns metadata for the specified queue. + This operation returns metadata, such as message TTL, for the queue. + queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. + + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Returns statistics for the specified queue. + This operation returns queue statistics, including how many messages are in the queue, categorized by status. + If the value of the total attribute is 0, then oldest and newest message statistics are not included in the response. + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Deletes the specified queue. + This operation immediately deletes a queue and all of its existing messages. + queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. + + + + + + + + + + + + + + + + + &commonFaults; + + + + + + + + Verifies whether the specified queue exists. + This operation verifies whether the specified queue exists. + You can also use HEAD instead of GET for the verb. + queue_name is the name that you give to the queue. The name must not exceed 64 bytes in length, and it is limited to US-ASCII letters, digits, underscores, and hyphens. + + + + + + + + + + + + + + + + + &getFaults; + + + + + + + + + + + + Posts the message or messages for the specified queue. + This operation posts the specified message or messages. + You can submit up to 10 messages in a single request, but you must always encapsulate the messages in a collection container (an array in JSON, even for a single message - without the JSON array, you receive the "Invalid request body" message). The resulting value of the Location header or response body might be used to retrieve the created messages for further processing. + The client specifies only the body and TTL for the message. The server inserts metadata, such as ID and age. + The response body contains a list of resource paths that correspond to each message submitted in the request, in the order of the messages. If a server-side error occurs during the processing of the submitted messages, a partial list is returned, the partial attribute is set to true, and the client tries to post the remaining messages again. If the server cannot enqueue any messages, the server returns a 503 Service Unavailable error message. + + The body attribute specifies an arbitrary document that constitutes the body of the message being sent.. + The following rules apply for the maximum size: + + + + + + The maximum size of posted messages is the maximum size of the entire request document (rather than the sum of the individual message body field values as it was in earlier releases). On error, the client will now be notified of how much it exceeded the limit. + + + The size is limited to 256 KB, including whitespace. + + + + The document must be valid JSON. (The Message Queuing service validates it.) + The ttl attribute specifies how long the server waits before marking the message as expired and removing it from the queue. The value of ttl must be between 60 and 1209600 seconds (14 days). Note that the server might not actually delete the message until its age has reached up to (ttl + 60) seconds, to allow for flexibility in storage implementations. + + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Gets the message or messages in the specified queue. + A request to list messages when the queue is not found or when messages are not found returns 204, instead of 200, because there was no information to send back. Messages with malformed IDs or messages that are not found by ID are ignored. + This operation gets the message or messages in the specified queue. + Message IDs and markers are opaque strings. Clients should make no assumptions about their format or length. Furthermore, clients should assume that there is no relationship between markers and message IDs (that is, one cannot be derived from the other). This allows for a wide variety of storage driver implementations. + Results are ordered by age, oldest message first. + + + + + Specifies an opaque string that the client can use to request the next batch of messages. The marker parameter communicates to the server which messages the client has already received. If you do not specify a value, the API returns all messages at the head of the queue (up to the limit). + + + + When more messages are available than can be returned in a single request, the client can pick up the next batch of messages by simply using the URI template parameters returned from the previous call in the "next" field. + Specifies up to 10 messages (the default value) to return. If you do not specify a value for the limit parameter, the default value of 10 is used. + + + + + Determines whether the API returns a client's own messages. The echo parameter is a Boolean value (true or false) that determines whether the API returns a client's own messages, as determined by the uuid portion of the User-Agent header. If you do not specify a value, echo uses the default value of false. If you are experimenting with the API, you might want to set echo=true in order to see the messages that you posted. + + + + + Determines whether the API returns claimed messages and unclaimed messages. The include_claimed parameter is a Boolean value (true or false) that determines whether the API returns claimed messages and unclaimed messages. If you do not specify a value, include_claimed uses the default value of false (only unclaimed messages are returned). + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Gets the specified message from the specified queue. + This operation gets the specified message from the specified queue. + If either the message ID is malformed or nonexistent, no message is returned. + Message fields are defined as follows:href is an opaque relative URI that the client can use to uniquely identify a message resource and interact with it.ttl is the TTL that was set on the message when it was posted. The message expires after (ttl - age) seconds.age is the number of seconds relative to the server's clock.body is the arbitrary document that was submitted with the original request to post the message. + + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Gets a specified set of messages from the specified queue. + This operation provides a more efficient way to query multiple messages compared to using a series of individual GETs. Note that the list of IDs cannot exceed 20. If a malformed ID or a nonexistent message ID is provided, it is ignored, and the remaining messages are returned. + Unlike the Get Messages operation, a client's own messages are always returned in this operation. If you use the ids parameter, the echo parameter is not used and is ignored if it is specified. + The message attributes are defined as follows:href is an opaque relative URI that the client can use to uniquely identify a message resource and interact with it.ttl is the TTL that was set on the message when it was posted. The message expires after (ttl - age) seconds.age is the number of seconds relative to the server's clock.body is the arbitrary document that was submitted with the original request to post the message. + + + + + Specifies the IDs of the messages to get. Format multiple message ID values by separating them with commas (comma-separated). + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Deletes the specified message from the specified queue. + This operation immediately deletes the specified message. + The claim_id parameter specifies that the message is deleted only if it has the specified claim ID and that claim has not expired. This specification is useful for ensuring only one worker processes any given message. When a worker's claim expires before it can delete a message that it has processed, the worker must roll back any actions it took based on that message because another worker can now claim and process the same message. + If you do not specify claim_id, but the message is claimed, the operation fails. You can only delete claimed messages by providing an appropriate claim_id. + + + + + Identifies the claim. + + + + + + + + + + + + + + + + &commonFaults; + &deleteFaults; + + + + + + + + Provides a bulk delete for messages. + This operation immediately deletes the specified messages. If any of the message IDs are malformed or non-existent, they are ignored. The remaining valid messages IDs are deleted. + + + + + Specifies the IDs of the messages to delete. + + + + + + + + + + + + + + + + &commonFaults; + &deleteFaults; + + + + + + + + + + + + Claims a set of messages from the specified queue. + This operation claims a set of messages (up to the value of the limit parameter) from oldest to newest and skips any messages that are already claimed. If no unclaimed messages are available, the API returns a 204 No Content message. + When a client (worker) finishes processing a message, it should delete the message before the claim expires to ensure that the message is processed only once. As part of the delete operation, workers should specify the claim ID (which is best done by simply using the provided href). If workers perform these actions, then if a claim simply expires, the server can return an error and notify the worker of the race condition. This action gives the worker a chance to roll back its own processing of the given message because another worker can claim the message and process it. + The age given for a claim is relative to the server's clock. The claim's age is useful for determining how quickly messages are getting processed and whether a given message's claim is about to expire. + When a claim expires, it is released. If the original worker failed to process the message, another client worker can then claim the message. + Note that claim creation is best-effort, meaning the worker may claim and return less than the requested number of messages. + The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours). You must include a value for this attribute in your request. + The grace attribute specifies the message grace period in seconds. The value of grace value must be between 60 and 43200 seconds (12 hours). You must include a value for this attribute in your request. To deal with workers that have stopped responding (for up to 1209600 seconds or 14 days, including claim lifetime), the server extends the lifetime of claimed messages to be at least as long as the lifetime of the claim itself, plus the specified grace period. If a claimed message would normally live longer than the grace period, its expiration is not adjusted. + + + + + Specifies the number of messages to claim. The limit parameter is configurable. + The default is 20. Messages + are claimed based on the number of messages available. + The server might claim and return less than the + requested number of messages. + + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + Queries the specified claim for the specified queue. + This operation queries the specified claim for the specified queue. Claims with malformed IDs or claims that are not found by ID are ignored. + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Updates the specified claim for the specified queue. + This operation updates the specified claim for the specified queue. Claims with malformed IDs or claims that are not found by ID are ignored. + Clients should periodically renew claims during long-running batches of work to avoid losing a claim while processing a message. The client can renew a claim by issuing a PATCH command to a specific claim resource and including a new TTL for the claim (which can be different from the original TTL). The server resets the age of the claim and applies the new TTL. + + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + + + + + + Releases the specified claim for the specified queue. + This operation immediately releases a claim, making any remaining, undeleted) messages that are associated with the claim available to other workers. Claims with malformed IDs or claims that are not found by ID are ignored. + This operation is useful when a worker is performing a graceful shutdown, fails to process one or more messages, or is taking longer than expected to process messages, and wants to make the remainder of the messages available to other workers. + + + + + + + + + + + + + + + + &commonFaults; + &getFaults; + + + diff --git a/doc/wadl/samples/auth-20.json b/doc/wadl/samples/auth-20.json new file mode 100644 index 000000000..6f45c945e --- /dev/null +++ b/doc/wadl/samples/auth-20.json @@ -0,0 +1,3 @@ +{ + "key":"value" +} \ No newline at end of file diff --git a/doc/wadl/samples/auth-20.xml b/doc/wadl/samples/auth-20.xml new file mode 100644 index 000000000..3016d1e0a --- /dev/null +++ b/doc/wadl/samples/auth-20.xml @@ -0,0 +1,4 @@ + + + + diff --git a/doc/wadl/samples/checkQueueExists_request-http.txt b/doc/wadl/samples/checkQueueExists_request-http.txt new file mode 100644 index 000000000..f6ef8d965 --- /dev/null +++ b/doc/wadl/samples/checkQueueExists_request-http.txt @@ -0,0 +1,3 @@ +GET /v1/queues/demoqueue HTTP/1.1 +Host: queues.api.openstack.org +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/checkQueueExists_response-http.txt b/doc/wadl/samples/checkQueueExists_response-http.txt new file mode 100644 index 000000000..1b4b7ff0c --- /dev/null +++ b/doc/wadl/samples/checkQueueExists_response-http.txt @@ -0,0 +1 @@ +HTTP/1.0 204 OK \ No newline at end of file diff --git a/doc/wadl/samples/claimMessages_request-http.txt b/doc/wadl/samples/claimMessages_request-http.txt new file mode 100644 index 000000000..6121418b3 --- /dev/null +++ b/doc/wadl/samples/claimMessages_request-http.txt @@ -0,0 +1,7 @@ +POST /v1/queues/demoqueue/claims HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/claimMessages_request.json b/doc/wadl/samples/claimMessages_request.json new file mode 100644 index 000000000..cbcbb090f --- /dev/null +++ b/doc/wadl/samples/claimMessages_request.json @@ -0,0 +1,4 @@ +{ + "ttl": 300, + "grace": 300 +} \ No newline at end of file diff --git a/doc/wadl/samples/claimMessages_response-http.txt b/doc/wadl/samples/claimMessages_response-http.txt new file mode 100644 index 000000000..99c32b636 --- /dev/null +++ b/doc/wadl/samples/claimMessages_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 201 OK +Content-Length: 162 +Content-Type: application/json; charset=utf-8 +Location: /v1/queues/demoqueue/claims/51db7067821e727dc24df754 \ No newline at end of file diff --git a/doc/wadl/samples/claimMessages_response.json b/doc/wadl/samples/claimMessages_response.json new file mode 100644 index 000000000..2a7b9b85a --- /dev/null +++ b/doc/wadl/samples/claimMessages_response.json @@ -0,0 +1,10 @@ +[ + { + "body": { + "event": "BackupStarted" + }, + "age": 239, + "href": "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754", + "ttl": 300 + } +] \ No newline at end of file diff --git a/doc/wadl/samples/createQueue_request-http.txt b/doc/wadl/samples/createQueue_request-http.txt new file mode 100644 index 000000000..11979ffd6 --- /dev/null +++ b/doc/wadl/samples/createQueue_request-http.txt @@ -0,0 +1,5 @@ +PUT /v1/queues/demoqueue HTTP/1.1 +Host: queues.api.openstack.org +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: diff --git a/doc/wadl/samples/createQueue_response-http.txt b/doc/wadl/samples/createQueue_response-http.txt new file mode 100644 index 000000000..667f966c3 --- /dev/null +++ b/doc/wadl/samples/createQueue_response-http.txt @@ -0,0 +1,3 @@ +HTTP/1.1 201 Created +Content-Length: 0 +Location: /v1/queues/demoqueue \ No newline at end of file diff --git a/doc/wadl/samples/deleteMessage_request-http.txt b/doc/wadl/samples/deleteMessage_request-http.txt new file mode 100644 index 000000000..4797070f1 --- /dev/null +++ b/doc/wadl/samples/deleteMessage_request-http.txt @@ -0,0 +1,7 @@ +DELETE /v1/queues/demoqueue/messages/51db6f78c508f17ddc924358 HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/deleteMessage_response-http.txt b/doc/wadl/samples/deleteMessage_response-http.txt new file mode 100644 index 000000000..79ba4d3fb --- /dev/null +++ b/doc/wadl/samples/deleteMessage_response-http.txt @@ -0,0 +1 @@ +HTTP/1.1 204 No Content \ No newline at end of file diff --git a/doc/wadl/samples/deleteMessages_request-http.txt b/doc/wadl/samples/deleteMessages_request-http.txt new file mode 100644 index 000000000..a9f2957c8 --- /dev/null +++ b/doc/wadl/samples/deleteMessages_request-http.txt @@ -0,0 +1,7 @@ +DELETE /v1/queues/demoqueue/messages?ids=50b68a50d6f5b8c8a7c62b01,50b68a50d6f5b8c8a7c62b02 HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/deleteMessages_response-http.txt b/doc/wadl/samples/deleteMessages_response-http.txt new file mode 100644 index 000000000..79ba4d3fb --- /dev/null +++ b/doc/wadl/samples/deleteMessages_response-http.txt @@ -0,0 +1 @@ +HTTP/1.1 204 No Content \ No newline at end of file diff --git a/doc/wadl/samples/deleteQueue_request-http.txt b/doc/wadl/samples/deleteQueue_request-http.txt new file mode 100644 index 000000000..93109575a --- /dev/null +++ b/doc/wadl/samples/deleteQueue_request-http.txt @@ -0,0 +1,6 @@ +DELETE /v1/queues/demoqueue HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/deleteQueue_response-http.txt b/doc/wadl/samples/deleteQueue_response-http.txt new file mode 100644 index 000000000..79ba4d3fb --- /dev/null +++ b/doc/wadl/samples/deleteQueue_response-http.txt @@ -0,0 +1 @@ +HTTP/1.1 204 No Content \ No newline at end of file diff --git a/doc/wadl/samples/getHomeDocument_request-http.txt b/doc/wadl/samples/getHomeDocument_request-http.txt new file mode 100644 index 000000000..5472e701c --- /dev/null +++ b/doc/wadl/samples/getHomeDocument_request-http.txt @@ -0,0 +1,2 @@ +GET /v1 HTTP/1.1 +Host: queues.api.openstack.org diff --git a/doc/wadl/samples/getHomeDocument_response-http.txt b/doc/wadl/samples/getHomeDocument_response-http.txt new file mode 100644 index 000000000..cbd111a8f --- /dev/null +++ b/doc/wadl/samples/getHomeDocument_response-http.txt @@ -0,0 +1,6 @@ +HTTP/1.0 200 OK +Cache-Control: max-age=86400 +Content-Length: 4345 +Content-Type: application/json-home +Date: Tue, 06 Sep 2013 16:31:48 GMT +Server: WSGIServer/0.1 Python/2.7.3 \ No newline at end of file diff --git a/doc/wadl/samples/getHomeDocument_response.json b/doc/wadl/samples/getHomeDocument_response.json new file mode 100644 index 000000000..7b8769466 --- /dev/null +++ b/doc/wadl/samples/getHomeDocument_response.json @@ -0,0 +1,119 @@ +{ + "resources": { + "rel/queue": { + "href-template": "/queues/{queue_name}", + "href-vars": { + "queue_name": "param/queue_name" + }, + "hints": { + "allow": [ + "GET", + "HEAD", + "PUT", + "DELETE" + ], + "formats": { + "application/json": {} + } + } + }, + "rel/queue-metadata": { + "href-template": "/queues/{queue_name}/metadata", + "href-vars": { + "queue_name": "param/queue_name" + }, + "hints": { + "allow": [ + "GET", + "PUT" + ], + "formats": { + "application/json": {} + } + } + }, + "rel/queue-stats": { + "href-template": "/queues/{queue_name}/stats", + "href-vars": { + "queue_name": "param/queue_name" + }, + "hints": { + "allow": [ + "GET" + ], + "formats": { + "application/json": {} + } + } + }, + "rel/queues": { + "href-template": "/queues{?marker,limit,detailed}", + "href-vars": { + "marker": "param/marker", + "detailed": "param/detailed", + "limit": "param/queue_limit" + }, + "hints": { + "allow": [ + "GET" + ], + "formats": { + "application/json": {} + } + } + }, + "rel/post-messages": { + "href-template": "/v1/queues/{queue_name}/messages", + "href-vars": { + "queue_name": "param/queue_name" + }, + "hints": { + "accept-post": [ + "application/json" + ], + "allow": [ + "POST" + ], + "formats": { + "application/json": {} + } + } + }, + "rel/messages": { + "href-template": "/queues/{queue_name}/messages{?marker,limit,echo,include_claimed}", + "href-vars": { + "marker": "param/marker", + "include_claimed": "param/include_claimed", + "queue_name": "param/queue_name", + "limit": "param/messages_limit", + "echo": "param/echo" + }, + "hints": { + "allow": [ + "GET" + ], + "formats": { + "application/json": {} + } + } + }, + "rel/claim": { + "href-template": "/v1/queues/{queue_name}/claims{?limit}", + "href-vars": { + "queue_name": "param/queue_name", + "limit": "param/claim_limit" + }, + "hints": { + "accept-post": [ + "application/json" + ], + "allow": [ + "POST" + ], + "formats": { + "application/json": {} + } + } + } + } +} \ No newline at end of file diff --git a/doc/wadl/samples/getMessages_request-http.txt b/doc/wadl/samples/getMessages_request-http.txt new file mode 100644 index 000000000..930345511 --- /dev/null +++ b/doc/wadl/samples/getMessages_request-http.txt @@ -0,0 +1,7 @@ +GET /v1/queues/demoqueue/messages?echo=true HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/getMessages_response-http.txt b/doc/wadl/samples/getMessages_response-http.txt new file mode 100644 index 000000000..f899e35ec --- /dev/null +++ b/doc/wadl/samples/getMessages_response-http.txt @@ -0,0 +1,6 @@ +HTTP/1.1 204 No Content + +HTTP/1.1 200 OK +Content-Length: 602 +Content-Type: application/json; charset=utf-8 +Content-Location: /v1/queues/demoqueue/messages?echo=true \ No newline at end of file diff --git a/doc/wadl/samples/getMessages_response.json b/doc/wadl/samples/getMessages_response.json new file mode 100644 index 000000000..8a6596e23 --- /dev/null +++ b/doc/wadl/samples/getMessages_response.json @@ -0,0 +1,42 @@ +{ + "messages": [ + { + "body": { + "event": "BackupStarted" + }, + "age": 198, + "href": "/v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad", + "ttl": 300 + }, + { + "body": { + "event": "BackupStarted" + }, + "age": 97, + "href": "/v1/queues/demoqueue/messages/51db6f2f821e727dc24df623", + "ttl": 300 + }, + { + "body": { + "event": "BackupStarted" + }, + "age": 24, + "href": "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357", + "ttl": 300 + }, + { + "body": { + "play": "hockey" + }, + "age": 24, + "href": "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924358", + "ttl": 60 + } + ], + "links": [ + { + "href": "/v1/queues/demoqueue/messages?marker=8&echo=true", + "rel": "next" + } + ] +} \ No newline at end of file diff --git a/doc/wadl/samples/getQueueMetadata_request-http.txt b/doc/wadl/samples/getQueueMetadata_request-http.txt new file mode 100644 index 000000000..e85c69a09 --- /dev/null +++ b/doc/wadl/samples/getQueueMetadata_request-http.txt @@ -0,0 +1,6 @@ +GET /v1/queues/demoqueue/metadata HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/getQueueMetadata_response-http.txt b/doc/wadl/samples/getQueueMetadata_response-http.txt new file mode 100644 index 000000000..bac97e0e9 --- /dev/null +++ b/doc/wadl/samples/getQueueMetadata_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Content-Length: 25 +Content-Type: application/json; charset=utf-8 +Content-Location: /v1/queues/demoqueue/metadata \ No newline at end of file diff --git a/doc/wadl/samples/getQueueMetadata_response.json b/doc/wadl/samples/getQueueMetadata_response.json new file mode 100644 index 000000000..a756ba96d --- /dev/null +++ b/doc/wadl/samples/getQueueMetadata_response.json @@ -0,0 +1 @@ +{"sms_template": "Warning: You have used {0}% of your storage ({1} out of {2}). Please consider upgrading your plan."} \ No newline at end of file diff --git a/doc/wadl/samples/getQueueStats_request-http.txt b/doc/wadl/samples/getQueueStats_request-http.txt new file mode 100644 index 000000000..6ea57d70b --- /dev/null +++ b/doc/wadl/samples/getQueueStats_request-http.txt @@ -0,0 +1,6 @@ +GET /v1/queues/demoqueue/stats HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/getQueueStats_response-http.txt b/doc/wadl/samples/getQueueStats_response-http.txt new file mode 100644 index 000000000..f60e26c9a --- /dev/null +++ b/doc/wadl/samples/getQueueStats_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Content-Length: 53 +Content-Type: application/json; charset=utf-8 +Content-Location: /v1/queues/demoqueue/stats \ No newline at end of file diff --git a/doc/wadl/samples/getQueueStats_response.json b/doc/wadl/samples/getQueueStats_response.json new file mode 100644 index 000000000..8613e8efc --- /dev/null +++ b/doc/wadl/samples/getQueueStats_response.json @@ -0,0 +1,17 @@ +{ + "messages": { + "claimed": 2409, + "free": 146929, + "total": 149338, + "newest": { + "age": 12, + "created": "2013-08-12T20:45:46Z", + "href": "/v1/queues/fizbit/messages/50b68a50d6f5b8c8a7c62b01" + }, + "oldest": { + "age": 63, + "created": "2013-08-12T20:44:55Z", + "href": "/v1/queues/fizbit/messages/50b68a50d6f5b8c8a7c62b01" + } + } +} \ No newline at end of file diff --git a/doc/wadl/samples/getSetMessagesByID_request-http.txt b/doc/wadl/samples/getSetMessagesByID_request-http.txt new file mode 100644 index 000000000..3060ce4ae --- /dev/null +++ b/doc/wadl/samples/getSetMessagesByID_request-http.txt @@ -0,0 +1,7 @@ +GET /v1/queues/demoqueue/messages?ids=51db6f78c508f17ddc924357,51db6ecac508f17ddc9242ad HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/getSetMessagesByID_response-http.txt b/doc/wadl/samples/getSetMessagesByID_response-http.txt new file mode 100644 index 000000000..b3c41e2aa --- /dev/null +++ b/doc/wadl/samples/getSetMessagesByID_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Content-Location: /v1/queues/fizbat/messages?ids=50b68a50d6f5b8c8a7c62b01,f5b8c8a7c62b0150b68a50d6 + +... \ No newline at end of file diff --git a/doc/wadl/samples/getSetMessagesByID_response.json b/doc/wadl/samples/getSetMessagesByID_response.json new file mode 100644 index 000000000..9bb8c7775 --- /dev/null +++ b/doc/wadl/samples/getSetMessagesByID_response.json @@ -0,0 +1,20 @@ +[ + { + "href": "/v1/queues/fizbit/messages/50b68a50d6f5b8c8a7c62b01", + "ttl": 800, + "age": 32, + "body": { + "cmd": "EncodeVideo", + "jobid": 58229 + } + }, + { + "href": "/v1/queues/fizbit/messages/f5b8c8a7c62b0150b68a50d6", + "ttl": 800, + "age": 790, + "body": { + "cmd": "EncodeAudio", + "jobid": 58201 + } + } +] \ No newline at end of file diff --git a/doc/wadl/samples/getSpecificMessage_request-http.txt b/doc/wadl/samples/getSpecificMessage_request-http.txt new file mode 100644 index 000000000..24e111460 --- /dev/null +++ b/doc/wadl/samples/getSpecificMessage_request-http.txt @@ -0,0 +1,7 @@ +GET /v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/getSpecificMessage_response-http.txt b/doc/wadl/samples/getSpecificMessage_response-http.txt new file mode 100644 index 000000000..3ea8e404b --- /dev/null +++ b/doc/wadl/samples/getSpecificMessage_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Content-Length: 126 +Content-Type: application/json; charset=utf-8 +Content-Location: /v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad \ No newline at end of file diff --git a/doc/wadl/samples/getSpecificMessage_response.json b/doc/wadl/samples/getSpecificMessage_response.json new file mode 100644 index 000000000..6634869e5 --- /dev/null +++ b/doc/wadl/samples/getSpecificMessage_response.json @@ -0,0 +1,8 @@ +{ + "body": { + "event": "BackupStarted" + }, + "age": 240, + "href": "/v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad", + "ttl": 300 +} \ No newline at end of file diff --git a/doc/wadl/samples/listQueues_request-http.txt b/doc/wadl/samples/listQueues_request-http.txt new file mode 100644 index 000000000..7088dcbe2 --- /dev/null +++ b/doc/wadl/samples/listQueues_request-http.txt @@ -0,0 +1,6 @@ +GET /v1/queues HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/listQueues_response-http.txt b/doc/wadl/samples/listQueues_response-http.txt new file mode 100644 index 000000000..a28b7177f --- /dev/null +++ b/doc/wadl/samples/listQueues_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Content-Length: 3170 +Content-Type: application/json; charset=utf-8 +Content-Location: /v1/queues \ No newline at end of file diff --git a/doc/wadl/samples/listQueues_response.json b/doc/wadl/samples/listQueues_response.json new file mode 100644 index 000000000..033b0a34d --- /dev/null +++ b/doc/wadl/samples/listQueues_response.json @@ -0,0 +1,50 @@ +{ + "queues": [ + { + "href": "/v1/queues/036b184b28fcb548349af623079119c6a966cbc", + "name": "036b184b28fcb548349af623079119c6a966cbc" + }, + { + "href": "/v1/queues/0441f28617afbdecf4887e635fd0777fb3cec38", + "name": "0441f28617afbdecf4887e635fd0777fb3cec38" + }, + { + "href": "/v1/queues/0f8f0eff158922874536efa9cf8412b9e0fd07a", + "name": "0f8f0eff158922874536efa9cf8412b9e0fd07a" + }, + { + "href": "/v1/queues/160f981379972a4a0afaee5f5394a5d960c410e", + "name": "160f981379972a4a0afaee5f5394a5d960c410e" + }, + { + "href": "/v1/queues/2888a4527d0a11a3d82202d800f8e90eebd60ea", + "name": "2888a4527d0a11a3d82202d800f8e90eebd60ea" + }, + { + "href": "/v1/queues/2ad8eeca7f53d480d8ca4885d620643bfc6a7f9", + "name": "2ad8eeca7f53d480d8ca4885d620643bfc6a7f9" + }, + { + "href": "/v1/queues/3926ce2051db957d76a04cb2ea2d89fd49e6894", + "name": "3926ce2051db957d76a04cb2ea2d89fd49e6894" + }, + { + "href": "/v1/queues/46b30ebd60186c30194039824e6405300dc0903", + "name": "46b30ebd60186c30194039824e6405300dc0903" + }, + { + "href": "/v1/queues/486d5af3e057ee1a430eee3ee845aeb60c900d3", + "name": "486d5af3e057ee1a430eee3ee845aeb60c900d3" + }, + { + "href": "/v1/queues/58e8622645f07c7673412acbed51abb97ddb25d", + "name": "58e8622645f07c7673412acbed51abb97ddb25d" + } + ], + "links": [ + { + "href": "/v1/queues?marker=58e8622645f07c7673412acbed51abb9", + "rel": "next" + } + ] +} \ No newline at end of file diff --git a/doc/wadl/samples/postMessage_request-http.txt b/doc/wadl/samples/postMessage_request-http.txt new file mode 100644 index 000000000..853c9fd80 --- /dev/null +++ b/doc/wadl/samples/postMessage_request-http.txt @@ -0,0 +1,7 @@ +POST /v1/queues/demoqueue/messages HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/postMessage_request.json b/doc/wadl/samples/postMessage_request.json new file mode 100644 index 000000000..b2e60e349 --- /dev/null +++ b/doc/wadl/samples/postMessage_request.json @@ -0,0 +1,14 @@ +[ + { + "ttl": 300, + "body": { + "event": "BackupStarted" + } + }, + { + "ttl": 60, + "body": { + "play": "hockey" + } + } +] \ No newline at end of file diff --git a/doc/wadl/samples/postMessage_response-http.txt b/doc/wadl/samples/postMessage_response-http.txt new file mode 100644 index 000000000..14f223942 --- /dev/null +++ b/doc/wadl/samples/postMessage_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 201 Created +Content-Length: 149 +Content-Type: application/json; charset=utf-8 +Location: /v1/queues/demoqueue/messages?ids=51db6f78c508f17ddc924357,51db6f78c508f17ddc924358 \ No newline at end of file diff --git a/doc/wadl/samples/postMessage_response.json b/doc/wadl/samples/postMessage_response.json new file mode 100644 index 000000000..ad8be9a90 --- /dev/null +++ b/doc/wadl/samples/postMessage_response.json @@ -0,0 +1,7 @@ +{ + "partial": false, + "resources": [ + "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357", + "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924358" + ] +} \ No newline at end of file diff --git a/doc/wadl/samples/queryClaim_request-http.txt b/doc/wadl/samples/queryClaim_request-http.txt new file mode 100644 index 000000000..766de1298 --- /dev/null +++ b/doc/wadl/samples/queryClaim_request-http.txt @@ -0,0 +1,7 @@ +GET /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/queryClaim_response-http.txt b/doc/wadl/samples/queryClaim_response-http.txt new file mode 100644 index 000000000..dbe36c000 --- /dev/null +++ b/doc/wadl/samples/queryClaim_response-http.txt @@ -0,0 +1,4 @@ +HTTP/1.1 200 OK +Content-Length: 263 +Content-Type: application/json; charset=utf-8 +Content-Location: /v1/queues/demoqueue/claims/51db7067821e727dc24df754 \ No newline at end of file diff --git a/doc/wadl/samples/queryClaim_response.json b/doc/wadl/samples/queryClaim_response.json new file mode 100644 index 000000000..0d4743865 --- /dev/null +++ b/doc/wadl/samples/queryClaim_response.json @@ -0,0 +1,15 @@ +{ + "age": 57, + "href": "/v1/queues/demoqueue/claims/51db7067821e727dc24df754", + "messages": [ + { + "body": { + "event": "BackupStarted" + }, + "age": 296, + "href": "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754", + "ttl": 300 + } + ], + "ttl": 300 +} \ No newline at end of file diff --git a/doc/wadl/samples/releaseClaim_request-http.txt b/doc/wadl/samples/releaseClaim_request-http.txt new file mode 100644 index 000000000..3a704f7ab --- /dev/null +++ b/doc/wadl/samples/releaseClaim_request-http.txt @@ -0,0 +1,7 @@ +DELETE /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/releaseClaim_response-http.txt b/doc/wadl/samples/releaseClaim_response-http.txt new file mode 100644 index 000000000..79ba4d3fb --- /dev/null +++ b/doc/wadl/samples/releaseClaim_response-http.txt @@ -0,0 +1 @@ +HTTP/1.1 204 No Content \ No newline at end of file diff --git a/doc/wadl/samples/setQueueMetadata_request-http.txt b/doc/wadl/samples/setQueueMetadata_request-http.txt new file mode 100644 index 000000000..579c81918 --- /dev/null +++ b/doc/wadl/samples/setQueueMetadata_request-http.txt @@ -0,0 +1,6 @@ +PUT /v1/queues/demoqueue/metadata HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/setQueueMetadata_request.json b/doc/wadl/samples/setQueueMetadata_request.json new file mode 100644 index 000000000..cb9186c66 --- /dev/null +++ b/doc/wadl/samples/setQueueMetadata_request.json @@ -0,0 +1,3 @@ +{ + "new metadata": "Omega" +} \ No newline at end of file diff --git a/doc/wadl/samples/setQueueMetadata_response-http.txt b/doc/wadl/samples/setQueueMetadata_response-http.txt new file mode 100644 index 000000000..9b6fb6fd4 --- /dev/null +++ b/doc/wadl/samples/setQueueMetadata_response-http.txt @@ -0,0 +1,2 @@ +HTTP/1.1 204 No Content +Location: /v1/queues/demoqueue/metadata \ No newline at end of file diff --git a/doc/wadl/samples/updateClaim_request-http.txt b/doc/wadl/samples/updateClaim_request-http.txt new file mode 100644 index 000000000..101027161 --- /dev/null +++ b/doc/wadl/samples/updateClaim_request-http.txt @@ -0,0 +1,7 @@ +PATCH /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 +Host: queues.api.openstack.org +Content-type: application/json +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 +Accept: application/json +X-Project-Id: \ No newline at end of file diff --git a/doc/wadl/samples/updateClaim_request.json b/doc/wadl/samples/updateClaim_request.json new file mode 100644 index 000000000..4e6292ccd --- /dev/null +++ b/doc/wadl/samples/updateClaim_request.json @@ -0,0 +1,4 @@ +{ + "ttl": 300, + "grace": 300 +} \ No newline at end of file diff --git a/doc/wadl/samples/updateClaim_response-http.txt b/doc/wadl/samples/updateClaim_response-http.txt new file mode 100644 index 000000000..79ba4d3fb --- /dev/null +++ b/doc/wadl/samples/updateClaim_response-http.txt @@ -0,0 +1 @@ +HTTP/1.1 204 No Content \ No newline at end of file diff --git a/test-requirements.txt b/test-requirements.txt index 45428031a..65e0b6fb6 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -19,3 +19,5 @@ requests>=1.1 # Documentation sphinx>=1.1.2,<1.2 oslo.sphinx +openstack-doc-tools>=0.8.2 +