From 0027c504cf669ef9c5939139427ba165e4b3a069 Mon Sep 17 00:00:00 2001 From: Constanze Kratel Date: Fri, 29 Aug 2014 16:19:57 -0500 Subject: [PATCH] Updated dev guide to include feedback from previous tech review Changed UTF-8 to plain-text under call sequence Updated Content Type header to payload_content_type Rewrote call sequence descriptions for clarity Changed title caps to sentence caps Removed cq-devguide.wdl, which was added by mistake Author: Constanze Kratel Change-Id: Iffeb69f2fbe8820fcb3f48190316b1f510787a3d --- docs/src/docbkx/ck-devguide.xml | 590 ++-- docs/src/wadl/normalized/cq-devguide.wadl | 3793 --------------------- 2 files changed, 265 insertions(+), 4118 deletions(-) delete mode 100644 docs/src/wadl/normalized/cq-devguide.wadl diff --git a/docs/src/docbkx/ck-devguide.xml b/docs/src/docbkx/ck-devguide.xml index 03a3f96e8..7ed5e4731 100644 --- a/docs/src/docbkx/ck-devguide.xml +++ b/docs/src/docbkx/ck-devguide.xml @@ -55,7 +55,7 @@ behalf based on their requested encryption algorithm and bit length.
- Intended Audience + Intended audience This guide assists software developers who want to develop applications using Barbican. To use this information, you should have access to an active OpenStack deployment and be familiar with the @@ -77,13 +77,13 @@
- Additional Resources + Additional resources You can find additional information about Barbican at https://github.com/openstack/barbican. For information about OpenStack, refer to http://docs.openstack.org/.
- Document Change History + Document change history This version of the Developer Guide replaces and obsoletes all previous versions. The most recent changes are described in the table above. @@ -93,9 +93,9 @@
- General API Information + General API information
- Barbican Core Concepts + Barbican core concepts Barbican Core Concepts @@ -144,8 +144,6 @@ xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml"> Authentication - Retrieving the - Authentication TokenTo authenticate access to OpenStack services, you must first issue an authentication request to OpenStack Identity to acquire an authentication token. To request an authentication @@ -164,7 +162,7 @@ For example, if the roles for a user change, existing tokens for that user are invalid.
- Retrieving the Authentication Token + Retrieving the authentication token The authenticate operation provides users with an authentication token and a list of regional cloud endpoints. The sample requests and responses in this section illustrate @@ -179,7 +177,7 @@ authentication token and the examples that follow show the request and response in JSON format.
Barbican Core Concepts
- + @@ -200,11 +198,11 @@ (500), serviceUnavailable (503) - Authentication Request for US Endpoint: JSON + Authentication request for US endpoint: JSON - Authentication Response for US Endpoint: JSON + Authentication response for US endpoint: JSON - Contract Versions + Contract versions The version defines the contract and build information for the API. The contract version denotes the data model and behavior @@ -249,7 +247,7 @@ the API might be available at any given time and are not guaranteed to be compatible with one another. - Sample Request URL for Contract Version 1.0 + Sample request URL for contract version 1.0 https://<endpoint>/v1.0/1234 @@ -259,7 +257,7 @@
- Request and Response Types + Request and response types The Barbican API supports JSON data serialization formats. You specify the request format by using the Content-Type header. The request format is @@ -267,7 +265,7 @@ have a request body. You can specify the response format in requests by using the Accept header.
Request for Authentication TokenRequest for authentication token
POST
- + @@ -296,16 +294,16 @@ - API Operations + API operations This chapter describes each of the operations. The following table summarizes all of the operations that are available:
- Examples of Barbican Call Sequences + Examples of Barbican call sequences
- Secrets Examples + Secrets examples The secrets resource provides access to the secret and keying data that is stored in the system. The secret schema represents the actual secret or key that @@ -325,7 +323,7 @@ A secret consists of the following elements:
Response FormatResponse format
- + @@ -397,309 +395,256 @@
- Examples of Secret Combinations - This section outlines the different request sequences - you can adhere to when storing secrets. Each sequence uses - different combinations for the content type and content encoding fields. The content type and - content encoding information is specified either in the - payload_content_type and - payload_content_encoding parameters - of a POST request or in the Accept - and Content-type headers of a GET - request. - The following request combinations are possible: - - - - One-step sequence to create and retrieve a secret - using UTF-8/ASCII format - - - One-step sequence to create and retrieve a secret - using binary format - - - Two-step sequence to create and retrieve a secret - using binary format - - - One-step sequence to create and retrieve a secret - using plain text format - - - -
- One-Step Sequence for Secrets Using - UTF-8/ASCII - The following table shows the sequence for creating and - retrieving a secret using UTF-8/ASCII format. When you - submit a POST request with the - payload_content_type parameter set to - text/plain and do not specify the - payload_content_encoding - parameter, the payload sent with the POST request - will be encrypted and you should receive a response - with a secret reference URL. - -
Elements of a SecretElements of a secret
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
One-Step UTF-8/ASCII Secret - Create/Retrieve
MethodContent TypeContent EncodingResult
POST secretstext/plainMust be omittedThe supplied payload is encrypted
GET secretsapplication/json for - Accept headerNot required/ignoredReturns JSON metadata, with - content-types field set - to "default": "text/plain".
GET secretstext/plain for Accept - headerNot required/ignoredReturns the decrypted payload from the previous - request.
- -
-
- One-Step Sequence for Binary Secrets - The following table shows the one-step sequence for - creating and retrieving a secret using binary format. When - you submit a POST request with the - payload_content_type parameter set to - application/octet-stream and the - payload_content_encoding - parameter set to base64, the payload - will be converted from base64 to binary format and encrypted. - You should also receive a response - with a secret reference URL. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
One-Step Binary Secret Create/Retrieve
MethodContent TypeContent EncodingResult
POST secretsapplication/octet-streambase64Supplied payload is converted from base64 to - binary, and then encrypted.
GET secretsapplication/json for - Accept headerNot required/ignoredJSON metadata, with the - content-types field set to - "default": - "application/octet-stream"
GET secretsapplication/octet-stream for - Accept headerNot specifiedPrevious payload is decrypted and returned as raw - binary, even if the POST request - provided data in base64 format.
-
-
- Two-Step Sequence for Binary Secrets - The following table shows the two-step sequence for - creating and retrieving a secret using binary format. First - submit a POST request without specifying - a payload, payload_content_type, or payload_content_encoding. - Submitting a POST request without this - information creates metadata for the secret. To add payload - information, submit a PUT request with the - secret id that was returned from the POST - request, and set the content type to application/octet - stream and the content encoding to base64. This will convert - the payload from base64 to binary format and then encrypt - it. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Two-Step Binary Secret - Create/Retrieve
MethodContent TypeContent EncodingResult
POST secretsNot required/ignoredNot required/ignoredOnly metadata is created. If the - payload_content_type or - payload_content_encoding - parameters were provided, they are not used or - saved with the metadata. The - subsequentPUT request - determines the secret's content type.
PUT secrets, first option - with content encoding set to base64Content-Type header set to - application/octet-streamContent-Encoding header set to - base64Supplied request body is converted from - base64 to binary, then - encrypted.
PUT secrets, second option - as binaryContent-Type header set to - application/octet-streamNot specifiedSupplied request body is encrypted as is.
GET secrets (metadata)Accept header set to - application/jsonNot required/ignoredReturns JSON metadata, with - content-types field set - to "default": - "application/octet-stream"
GET secrets (decrypted)Accept header set to - application/octet-streamNot required/ignoredThe previous request is decrypted and returned - as raw binary.
- -
-
- Two-Step Sequence for Plain Text Secrets - The following table shows the two-step sequence for - creating and retrieving a secret using binary format. First - submit a POST request without - specifying a payload, payload_content_type, or - payload_content_encoding. Submitting a POST - request without payload creates metadata for the secret. - To add payload information, submit a - PUT request with the secret id that - was returned from the POST request, and - set the content type to text/plain which will - store the payload as is. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Two-Step Plain-Text Secret - Create/Retrieve
ActionContent TypeContent EncodingResult
POSTNot required/ignoredNot required/ignoredOnly metadata is created. If the - payload_content_type or - payload_content_encoding - parameters were provided, they are not used or - saved with the metadata. The subsequent - PUT request specifies the - content format for the secret.
PUT Content-Type header is set to - text/plain.Not required/ignoredSupplied request body is encrypted as is.
GETAccept header is set to - application/json.Not required/ignoredReturns JSON metadata, with the - content-types field set - to "default": "text/plain"
GETAccept header is set to - text/plain.Not specifiedThe previous request is decrypted and returned - as UTF-8 text.
- -
+ Examples of secret combinations + The following request combinations are possible: + + + + One-step sequence to store and + retrieve a plain-text secrett + + + One-step sequence to store and + retrieve a binary secret + + + Two-step sequence to store and + retrieve a binary secret + + + Two-step sequence to store and + retrieve a plain-text secret + + + +
+ One-step sequence for storing and retrieving a plain-text secret + The following table shows the sequence for storing and retrieving a plain-text + secret. When you submit a POST request with the + payload_content_type parameter set to + text/plain and do not specify the + payload_content_encoding parameter, the payload sent with + the POST request is encrypted and stored, and then a response + is sent with a reference URL to the secret. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
One-step plain-text secret store and retrieve
MethodContent typeContent encodingResult
POST secretspayload_content_type is set to text/plainNot required, is ignored if provided.The supplied payload is encrypted and stored.
GET secretsAccept header is set to application/jsonNot required, is ignored if provided Returns JSON metadata, with the content-types + field set to "default":"text/plain".
GET secretsAccept header is set to text/plainNot required, is ignored if provided Returns the decrypted plain-text payload from the previous request.
+ +
+
+ One-step sequence for storing and retrieving binary secrets + The following table shows the one-step sequence for storing and retrieving a + binary secret. When you submit a POST request with the + payload_content_type parameter set to + application/octet-stream and the + payload_content_encoding parameter set to + base64, the payload is converted from base64 to binary format and + encrypted and then stored. You should also receive a response with a reference URL + to the secret. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
One-step binary secret store and retrieve
MethodContent typeContent encodingResult
POST + Content-Type header is set to + application/octet-streambase64Supplied payload is converted from base64 to binary, and then + encrypted.
GET + Accept header is set to application/jsonNot required, is ignored if provided Returns JSON metadata, with the content-types field + set to "default":"application/octet-stream"
GETAccept header is set to application/octet-stream + Not specifiedStored secret is decrypted and returned as raw binary, even if the + POST request provided data in base64 + format.
+
+
+ Two-step sequence for storing and retrieving plain-text secrets + The following table shows the two-step sequence for storing and retrieving a + plain-text secret. First, you submit a POST request without + specifying a payload, payload_content_type, or + payload_content_encoding. Submitting a POST + request without this information creates metadata for the secret. To upload, + encrypt, and store the secret, submit a PUT request with the + secret's reference URL that was returned from the POST request, + and set the Content-Type header to application/octet + stream. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Two-step plain-text secret store and retrieve
MethodContent typeContent encodingResult
POST + Not required, is ignored if provided Not required, is ignored if provided Only metadata is created. If the + payload_content_type or + payload_content_encoding parameters are provided, + they are not used or saved with the metadata. The + subsequentPUT request determines the secret's content + type.
PUT secrets with base64-format secretContent-Type header is set to text/plainNot required, is ignored if providedSupplied request body is encrypted as is.
GET secrets (metadata)Accept header is set to text/plainNot required, is ignored if provided Returns JSON metadata, with content-types field + set to "default": "application/octet-stream".
GET secrets (decrypted)Accept header is set to + application/octet-streamNot required, is ignored if provided The previous request is decrypted and returned as raw binary.
+ +
+
+ Two-step sequence for storing and retrieving binary secrets + The following table shows the two-step sequence for storing and retrieving a + binary secret. First submit a POST request without specifying a + payload, payload_content_type, or + payload_content_encoding. Submitting a POST + request without payload creates metadata for the secret. To upload base64-format + secrets, set the Content-Encoding header to base64. To + upload binary secrets, do not set the Content-Encoding header. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Two-step binary secret store and retrieve
ActionContent typeContent encodingResult
POSTNot required, is ignored if provided Not required, is ignored if provided Only metadata is created. If the + payload_content_type or + payload_content_encoding parameters are provided, + they are not used or saved with the metadata. The subsequent + PUT request specifies the content format for the + secret.
PUT Content-Type header is set to text/plain.Not required, is ignored if provided Supplied request body is encrypted as is.
GETAccept header is set to application/json.Not required, is ignored if provided Returns JSON metadata, with the content-types + field set to "default": "text/plain".
GETAccept header is set to text/plain.Not required, is ignored if provided The previous request is decrypted and returned as UTF-8 text.
+ +
- Orders Examples + Orders examples The orders resource allows for the generation of secret material by Barbican. The ordering object encapsulates the workflow and history for the creation of a secret. This @@ -784,13 +729,8 @@ POST request at a command-line interface, as shown in the following example: - - Uploading an Order JSON Request - Example - - + - Make sure to have a payload specified, as well as a corresponding content type and content diff --git a/docs/src/wadl/normalized/cq-devguide.wadl b/docs/src/wadl/normalized/cq-devguide.wadl deleted file mode 100644 index 841dffa1c..000000000 --- a/docs/src/wadl/normalized/cq-devguide.wadl +++ /dev/null @@ -1,3793 +0,0 @@ - - - - - Arbitrary character string generated by the - authentication service in response to - valid credentials. - - - - 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. - - - - - - GET /v1 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com - - - - - - - - - - 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 - -{ - "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": {} - } - } - } - } -} - - - - - - - - - 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. - - - - - - GET /v1/queues HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 3170 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues - -{ - "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" - } - ] -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies the name of the queue. - - - - 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. - - - - - - - PUT /v1/queues/demoqueue HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -{ - -} - - - - - - - - - - - HTTP/1.1 201 Created -Content-Length: 0 -Location: /v1/queues/demoqueue - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - DELETE /v1/queues/demoqueue HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - Checks to - - GET /v1/queues/demoqueue HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -X-Project-Id: 806067 - - - - - - - - - HTTP/1.0 204 OK - - - - - - - - - - - - - - - - Sets metadata for the specified queue. - This operation sets metadata for the specified queue. - The request body has a limit of 256 KB, excluding whitespace. - 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 maximum size of this body is 256 KB, excluding whitespace (when re-serialized as JSON). The document must be valid JSON. (Cloud Queues validate 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. - - - - - - - PUT /v1/queues/demoqueue/metadata HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -{ - "new metadata": "Omega" -} - - - - - - - - - - HTTP/1.1 204 No Content -Location: /v1/queues/demoqueue/metadata - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - GET /v1/queues/demoqueue/metadata HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 25 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/metadata - -{"new metadata": "Omega"} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - GET /v1/queues/demoqueue/stats HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 53 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/stats - -{ - "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" - } - } -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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). 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 size of this body is limited to 256 KB, excluding whitespace. The document must be valid JSON. (Cloud Queues 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. - - - - - - POST /v1/queues/demoqueue/messages HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -[ - { - "ttl": 300, - "body": { - "event": "BackupStarted" - } - }, - { - "ttl": 60, - "body": { - "play": "hockey" - } - } -] - - - - - - - - - - HTTP/1.1 201 Created -Content-Length: 149 -Content-Type: application/json; charset=utf-8 -Location: /v1/queues/demoqueue/messages?ids=51db6f78c508f17ddc924357,51db6f78c508f17ddc924358 - -{ - "partial": false, - "resources": [ - "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357", - "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924358" - ] -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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). - - - - - - GET /v1/queues/demoqueue/messages?echo=true HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - 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 - -{ - "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" - } - ] -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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 GET. 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). - - - - - Specifies the claim ID with which the message is associated. - - - - - - GET /v1/queues/demoqueue/messages?ids=51db6f78c508f17ddc924357,51db6ecac508f17ddc9242ad HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - - HTTP/1.1 200 OK -Content-Location: /v1/queues/fizbat/messages?ids=50b68a50d6f5b8c8a7c62b01,f5b8c8a7c62b0150b68a50d6 - -... - -[ - { - "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 - } - } -] - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - DELETE /v1/queues/demoqueue/messages?ids=50b68a50d6f5b8c8a7c62b01,50b68a50d6f5b8c8a7c62b02 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies the message ID. - - - - 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. - - - - - - - - - GET /v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 126 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad - -{ - "body": { - "event": "BackupStarted" - }, - "age": 240, - "href": "/v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad", - "ttl": 300 -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - DELETE /v1/queues/demoqueue/messages/51db6f78c508f17ddc924358 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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 thia 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 return, up to 20 messages. If limit is not specified, limit defaults to 10. - - - - - - POST /v1/queues/demoqueue/claims HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -{ - "ttl": 300, - "grace": 300 -} - - - - - - - - - HTTP/1.1 201 OK -Content-Length: 162 -Content-Type: application/json; charset=utf-8 -Location: /v1/queues/demoqueue/claims/51db7067821e727dc24df754 - -[ - { - "body": { - "event": "BackupStarted" - }, - "age": 239, - "href": "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754", - "ttl": 300 - } -] - - - - - - - - - - - - - - - - - - - - - - - - - - - - Specifies the claim ID. - - - - 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. - - - - - - GET /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 263 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/claims/51db7067821e727dc24df754 - -{ - "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 -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - PATCH /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - -{ - "ttl": 300, - "grace": 300 -} - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - DELETE /v1/480924/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - GET /v1 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com - - - - - - - - - - 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 - -{ - "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": {} - } - } - } - } -} - - - - - - - - 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. - - - - - - - PUT /v1/queues/demoqueue HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -{ - -} - - - - - - - - - - - HTTP/1.1 201 Created -Content-Length: 0 -Location: /v1/queues/demoqueue - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - GET /v1/queues HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 3170 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues - -{ - "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" - } - ] -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - Sets metadata for the specified queue. - This operation sets metadata for the specified queue. - The request body has a limit of 256 KB, excluding whitespace. - 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 maximum size of this body is 256 KB, excluding whitespace (when re-serialized as JSON). The document must be valid JSON. (Cloud Queues validate 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. - - - - - - - PUT /v1/queues/demoqueue/metadata HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -{ - "new metadata": "Omega" -} - - - - - - - - - - HTTP/1.1 204 No Content -Location: /v1/queues/demoqueue/metadata - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - GET /v1/queues/demoqueue/metadata HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 25 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/metadata - -{"new metadata": "Omega"} - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - GET /v1/queues/demoqueue/stats HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 53 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/stats - -{ - "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" - } - } -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - DELETE /v1/queues/demoqueue HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - Checks to - - GET /v1/queues/demoqueue HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -X-Project-Id: 806067 - - - - - - - - - HTTP/1.0 204 OK - - - - - - - - - - - - - - - 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). 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 size of this body is limited to 256 KB, excluding whitespace. The document must be valid JSON. (Cloud Queues 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. - - - - - - POST /v1/queues/demoqueue/messages HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -[ - { - "ttl": 300, - "body": { - "event": "BackupStarted" - } - }, - { - "ttl": 60, - "body": { - "play": "hockey" - } - } -] - - - - - - - - - - HTTP/1.1 201 Created -Content-Length: 149 -Content-Type: application/json; charset=utf-8 -Location: /v1/queues/demoqueue/messages?ids=51db6f78c508f17ddc924357,51db6f78c508f17ddc924358 - -{ - "partial": false, - "resources": [ - "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357", - "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924358" - ] -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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). - - - - - - GET /v1/queues/demoqueue/messages?echo=true HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - 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 - -{ - "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" - } - ] -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - - - GET /v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 126 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad - -{ - "body": { - "event": "BackupStarted" - }, - "age": 240, - "href": "/v1/queues/demoqueue/messages/51db6ecac508f17ddc9242ad", - "ttl": 300 -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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 GET. 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). - - - - - Specifies the claim ID with which the message is associated. - - - - - - GET /v1/queues/demoqueue/messages?ids=51db6f78c508f17ddc924357,51db6ecac508f17ddc9242ad HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - - HTTP/1.1 200 OK -Content-Location: /v1/queues/fizbat/messages?ids=50b68a50d6f5b8c8a7c62b01,f5b8c8a7c62b0150b68a50d6 - -... - -[ - { - "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 - } - } -] - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - DELETE /v1/queues/demoqueue/messages/51db6f78c508f17ddc924358 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - DELETE /v1/queues/demoqueue/messages?ids=50b68a50d6f5b8c8a7c62b01,50b68a50d6f5b8c8a7c62b02 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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 thia 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 return, up to 20 messages. If limit is not specified, limit defaults to 10. - - - - - - POST /v1/queues/demoqueue/claims HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Accept: application/json -X-Project-Id: 806067 - -{ - "ttl": 300, - "grace": 300 -} - - - - - - - - - HTTP/1.1 201 OK -Content-Length: 162 -Content-Type: application/json; charset=utf-8 -Location: /v1/queues/demoqueue/claims/51db7067821e727dc24df754 - -[ - { - "body": { - "event": "BackupStarted" - }, - "age": 239, - "href": "/v1/queues/demoqueue/messages/51db6f78c508f17ddc924357?claim_id=51db7067821e727dc24df754", - "ttl": 300 - } -] - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - GET /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 200 OK -Content-Length: 263 -Content-Type: application/json; charset=utf-8 -Content-Location: /v1/queues/demoqueue/claims/51db7067821e727dc24df754 - -{ - "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 -} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - PATCH /v1/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - -{ - "ttl": 300, - "grace": 300 -} - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - DELETE /v1/480924/queues/demoqueue/claims/51db7067821e727dc24df754 HTTP/1.1 -Host: ord.queues.api.rackspacecloud.com -Content-type: application/json -X-Auth-Token: 0f6e9f63600142f0a970911583522217 -Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830 -Accept: application/json -X-Project-Id: 806067 - - - - - - - - - HTTP/1.1 204 No Content - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file