Queues#

This section describes queue operations that are supported by the Rackspace Cloud Queues API.

List queues#

GET /v1/{project_id}/queues

This operation lists queues for the project. The queues are sorted alphabetically by name.

A request to list queues when you have no queues in your account returns HTTP 204, instead of HTTP 200, because there was no information to send back.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Success. The URI might have an invalid parameter (something other than limit, marker, or detailed), but the invalid parameter is ignored.

204

No content

You have no queues in your account, or the request has a non- existing value for marker.

400

Bad request

The request has a negative or zero value for the limit, a non- boolean value for detailed, or a header that has missing fields.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

The requested queue does not exist.

406

Not acceptable

The request header has Accept !=”application/json”.

429

Too many requests

Too many requests.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

The following table shows the query parameters for the request:

Name

Type

Description

marker

String (Optional)

Specifies the name of the last queue received in a previous request, or none to get the first page of results.

limit

Integer (Optional)

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.

detailed

Boolean (Optional)

Determines whether queue metadata is included in the response. The default value for this parameter is false, which excludes the metadata.

Note

This operation does not accept a request body.

Example List queues: JSON request

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

Response#

Example List queues: JSON response

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"
      }
   ]
}

Create queue#

PUT /v1/{project_id}/queues/{queue_name}

This operation creates a new queue.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

201

Created

The request has been fulfilled and the queue was created.

204

No content

Success. The queue already exists.

400

Bad request

The queue has a long name (greater than 64 bytes).

400

Bad request

The request header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

429

Too many requests

Too many requests.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

{queue_name}

String

The name of 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.

Note

This operation does not accept a request body.

Example Create queue: JSON request

PUT /v1/queues/demoqueue HTTP/1.1
Host: ord.queues.api.rackspacecloud.com
X-Auth-Token: 0f6e9f63600142f0a970911583522217
Accept: application/json
X-Project-Id: 806067

Response#

Example Create queue: JSON response

HTTP/1.1 201 Created
Content-Length: 0
Location: /v1/queues/demoqueue

Delete queue#

DELETE /v1/{project_id}/queues/{queue_name}

This operation immediately deletes a queue and all of its existing messages.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The URI has invalid parameters. The invalid parameters are ignored.

204

No content

Delete of a non-existing queue.

204

No content

Success.

400

Bad request

The header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

406

Not acceptable

The request header has Accept !=”application/json”.

429

Too many requests

Too many requests.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

{queue_name}

String

The name of 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.

Note

This operation does not accept a request body.

Example Delete queue: JSON request

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

Response#

Example Delete queue: JSON response

HTTP/1.1 204 No Content

Check queue existence#

GET /v1/{project_id}/queues/{queue_name}

This operation verifies whether the specified queue exists.

You can also use HEAD instead of GET for the verb.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

204

OK

The requested queue exists.

404

Not found

The requested queue does not exist.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

{queue_name}

String

The name of 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.

Note

This operation does not accept a request body.

Example Check queue existence: JSON request

GET /v1/queues/demoqueue HTTP/1.1
Host: ord.queues.api.rackspacecloud.com
X-Project-Id: 806067

Response#

Example Check queue existence: JSON response

HTTP/1.0 204 OK

Set queue metadata#

PUT /v1/{project_id}/queues/{queue_name}/metadata

This operation sets metadata for the specified queue.

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 request body has a limit of 256 KB, including whitespace (when re-serialized as JSON).

The body of the request includes contextual information about the way a particular application interacts with the queue. The document must be valid JSON (Cloud Queues validates it).

The following table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

Success.

400

Bad request

The request body is empty.

400

Bad request

The request body is greater than 64 KB.

400

Bad request

The request body is not JSON.

400

Bad request

The request has a UTF-16 char JSON body.

400

Bad request

The request has malformed JSON.

406

Not acceptable

The request header has Accept !=”application/json”.

429

Too many requests

Too many requests.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

{queue_name}

String

The name of 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.

Example Set queue metadata: JSON request

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"
}

Response#

Example Set queue metadata: JSON response

HTTP/1.1 204 No Content
Location: /v1/queues/demoqueue/metadata

Show queue metadata#

GET /v1/{project_id}/queues/{queue_name}/metadata

This operation returns metadata, such as message TTL, for the queue.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Success, or no metadata exists for the queue, or the URI has invalid parameters and the invalid parameters are ignored.

400

Bad request

The request header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

Metadata was requested for a queue that does not exist.

406

Not acceptable

The request header has Accept !=”application/json”.

429

Too many requests

Too many requests.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

{queue_name}

String

The name of 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.

Note

This operation does not accept a request body.

Example Show queue metadata: JSON request

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

Response#

Example Show queue metadata: JSON response

HTTP/1.1 200 OK
Content-Length: 25
Content-Type: application/json; charset=utf-8
Content-Location: /v1/queues/demoqueue/metadata

{
   "new metadata":"Omega"
}

Show queue stats#

GET /v1/{project_id}/queues/{queue_name}/stats

This operation returns queue statistics, including how many messages are in the queue, categorized by status.

Note

If the value of the total parameter is 0, then oldest and newest message statistics are not included in the response.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

Success, or the URI has invalid parameters, but the invalid parameters are ignored.

400

Bad request

The request header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

Stats were requested for a queue that does not exist.

406

Not acceptable

The request header has Accept !=”application/json”.

429

Too many requests

Too many requests.

Request#

The following table shows the URI parameters for the request:

Name

Type

Description

{project_id}

String

The project ID for the user. If you do not set the X- Project-Id header in the request, use project_id in the URI. For example: GET https://ord.queues.api.rackspacecloud.com/v1/{project_id}

{queue_name}

String

The name of 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.

Note

This operation does not accept a request body.

Example Show queue stats: JSON request

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

Response#

Example Show queue stats: JSON response

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"
      }
   }
}