REST Requests

Amazon SQS supports REST requests for calling service actions. REST requests are HTTP requests (see http://www.w3.org/Protocols/rfc2616/rfc2616.html to understand the parts of HTTP requests).

Unlike SQS Query requests, REST requests don't have an Action parameter. Instead the action is indicated by the HTTP method (GET, PUT, etc.) and the request's endpoint. The other parts of SQS REST requests are discussed below.

The REST response is an XML document that conforms to a schema, which is discussed in WSDL and Schema Location.

	Important
	The Amazon SQS REST API does not include support for access control. The Query and SOAP APIs do.

Structure of a REST Request

The following list describes the main parts of an SQS REST request:

HTTP method—This is the verb in the request (GET, PUT, DELETE, etc.)
Endpoint—In HTTP requests, the endpoint is the resource you want to act on. The resource is indicated by the combination of the host (contained in the request's Host header) and the URI. For SQS, the host is always queue.amazonaws.com, so the URI itself is how you specify the particular endpoint you want to act on. For SQS, you can act on the service itself, an SQS queue, or an SQS message. These are represented by endpoints called Service, MessageQueue, and Message respectively.
Protocol version—HTTP requests include the HTTP protocol version after the URI. For example: HTTP/1.1. See the examples below.
Headers—HTTP requests include headers that contain basic information about the request. SQS REST requests have required headers and optional headers, as described in Common REST Headers. Headers use the format <header name>: <header value>. The requests below include the required headers Host, Authorization, Date, Content-Type, and AWS-Version.
Message body—HTTP requests can optionally contain information in the message body. For example, when you make a request to send a message to a queue, you'll include the message content in the request's message body.
Parameters—HTTP requests can optionally contain parameters in the URI, sometimes referred to as query parameters. These are name-value pairs separated from the endpoint by a question mark (?) and separated from each other by ampersands (&). Some of the SQS actions require you to include parameters in the URI. For example, in the example request below that sets the visibility timeout for a queue, the request includes an Attribute parameter and a Value parameter. Because the parameters appear in the URI, their values must be URL encoded.

Example REST Requests

The two examples below show you the different parts of SQS REST requests.

The first example acts on a MessageQueue endpoint generically identified here as QueueURL. For information about what a real queue URL looks like, see About the Queue URL.

	Important
	When specifying a queue when using the REST API, you must omit `http://queue.amazon.aws.com` from the queue URL and provide only what's left. For example, if the full queue URL is `http://queue.amazon.aws.com/A29E9WXPHGOG29/queue1`, for a REST request you provide only `/A29E9WXPHGOG29/queue1`. For an example, see the example request in PUT on MessageQueue).

The request sets the visibility timeout for the queue. Note that this action requires the use of query parameters Attribute and Value.

PUT /QueueURL?Attribute=VisibilityTimeout&Value=60 HTTP/1.1
Host: queue.amazonaws.com
Authorization: [AWS authentication string]
Date: Mon, 23 Apr 2007 21:12:00 GMT
Content-Type: text/plain
AWS-Version: 2007-05-01

The second example acts on a Message endpoint generically identified here as QueueURL/MessageID. The request deletes the message from the queue. Note that this action doesn't require the use of any query parameters.

DELETE /QueueURL/MessageId HTTP/1.1
Host: queue.amazonaws.com
Authorization: [AWS authentication string]
Date: Mon, 23 Apr 2007 21:12:00 GMT
Content-Type: text/plain
AWS-Version: 2007-05-01

REST Requests

Structure of a REST Request

Example REST Requests

Related Topics