Messages#

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

Note

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.

Post message#

POST /v1/{project_id}/queues/{queue_name}/messages

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 parameter 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 parameter 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. (Cloud Queues validates it.)

The ttl parameter 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.

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

Response Code

Name

Description

200

OK

The URI might have invalid parameters, but the invalid parameters are ignored.

201

Created

Success. With “partial”: true, multiple messages were posted in a single request and some of them succeeded.

400

Bad request

An attempt was made to post more than 100 messages with a single request.

400

Bad request

An attempt was made to post with a TTL greater than 1209600.

400

Bad request

An attempt was made to post with a TTL less than 60.

400

Bad request

An attempt was made to post with a negative value for TTL.

400

Bad request

An attempt was made to post with a non-JSON message.

400

Bad request

An attempt was made to post with a non-integer value for TTL.

400

Bad request

An attempt was made to post with messages encapsulated in multiple arrays.

400

Bad request

An attempt was made to post with no request body.

400

Bad request

An attempt was made to post with request body greater than 4 KB.

400

Bad request

An attempt was made to post without TTL in the request body.

400

Bad request

An attempt was made to post without the body parameter in request body.

400

Bad request

The post request included a non-JSON body.

400

Bad request

The post request included an invalid JSON body.

400

Bad request

The request header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

An attempt was made to post a message to a non- existing queue.

406

Not acceptable

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

429

Too many requests

Too many requests.

503

Service unavailable

An attempt was made to post multiple messages in a single request and all of them failed.

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 Post message: JSON request

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

Response#

Example Post message: JSON response

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

Get messages#

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

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.

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.

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

Response Code

Name

Description

200

OK

Success. One or more messages were found. The request might have included an invalid parameter (something other than marker, limit, echo, or include_claimed).

204

No content

A message with a non- existing marker was requested.

204

No content

Success, but no messages matched the request. Or, a message with a non- existing marker was requested.

400

Bad request

An attempt was made to request messages with a limit greater than 100.

400

Bad request

An attempt was made to request messages with a limit less than or equal to 0.

400

Bad request

An attempt was made to request messages with a non-boolean value for echo.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

An attempt was made to request a message from a non-existing queue.

406

Not acceptable

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

429

Too many requests

Too many requests.

503

Service unavailable

The server is currently unavailable.

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.

The following table shows the query parameters for the request:

Name

Type

Description

marker

String (Optional)

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).

limit

Integer (Optional)

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.

echo

Boolean (Optional)

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.

include_claimed

Boolean (Optional)

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).

Note

This operation does not accept a request body.

Example Get messages: JSON request

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

Response#

Example Get messages: JSON response

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

Get messages by ID#

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

This operation provides a more efficient way to query multiple messages compared to using a series of individual GET s. 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 body parameters 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.

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

Response Code

Name

Description

200

OK

Success. The URI might have invalid parameters, but invalid parameters are ignored.

400

Bad request

An attempt was made to request messages with a limit greater than 100.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

An attempt was made to request a message from a non-existing queue.

404

Not found

An attempt was made to request messages with a limit less than or equal to 0.

404

Not found

An attempt was made to request messages with a non-boolean value for echo.

406

Not acceptable

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

429

Too many requests

Too many requests.

503

Service unavailable

The server is currently unavailable.

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.

The following table shows the query parameters for the request:

Name

Type

Description

ids

String (Optional)

Specifies the IDs of the messages to get. Format multiple message ID values by separating them with commas (comma- separated).

Note

This operation does not accept a request body.

Example Get messages by ID: JSON request

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

Response#

Example Get messages by ID: JSON response

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

Bulk-delete messages by ID#

DELETE /v1/{project_id}/queues/{queue_name}/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.

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

Response Code

Name

Description

204

No content

Success.

204

No content

The request attempts to delete a message from a non-existing queue.

204

No content

The request attempts to delete a non-existing message.

400

Bad request

The header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

403

Forbidden

An attempt was made to delete a claimed message without providing a claim ID.

403

Forbidden

An attempt was made to delete messages with an expired claim ID.

403

Forbidden

An attempt was made to delete messages with non- existing claim ID.

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.

The following table shows the query parameters for the request:

Name

Type

Description

ids

String (Required)

Specifies the IDs of the messages to delete.

Note

This operation does not accept a request body.

Example Bulk-delete messages by ID: JSON request

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

Response#

Example Bulk-delete messages by ID: JSON response

HTTP/1.1 204 No Content

Show message details#

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

This operation shows details for the specified message from the specified queue.

If either the message ID is malformed or nonexistent, no message is returned.

Message body parameters 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.

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

Response Code

Name

Description

200

OK

Success. The request found a matching message. The URI might have invalid parameters, but the invalid parameters are ignored.

400

Bad request

The header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

404

Not found

An attempt was made to request a message from a non-existing queue.

404

Not found

An attempt was made to request a non-existing message.

404

Not found

An attempt was made to request an expired message.

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.

{messageId}

String

The message ID.

Note

This operation does not accept a request body.

Example Show message details: JSON request

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

Response#

Example Show message details: JSON response

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
}

Delete message#

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

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.

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

Success.

204

No content

The request attempts to delete a message from a non-existing queue.

204

No content

The request attempts to delete a non-existing message.

400

Bad request

The header has missing fields.

401

Unauthorized

The request header has an invalid auth token.

403

Forbidden

An attempt was made to delete a claimed message without providing a claim ID.

403

Forbidden

An attempt was made to delete a message with an expired claim ID.

403

Forbidden

An attempt was made to delete a message with non-existing claim ID.

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.

{messageId}

String

The message ID.

The following table shows the query parameters for the request:

Name

Type

Description

claim_id

String (Optional)

Identifies the claim.

Note

This operation does not accept a request body.

Example Delete message: JSON request

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

Response#

Example Delete message: JSON response

HTTP/1.1 204 No Content