Menu
Amazon AppStream
Developer Guide

This documentation is for an older version of Amazon AppStream. For information about the latest version, see the Amazon AppStream 2.0 Developer Guide.

Making HTTP Requests to Amazon AppStream

Amazon AppStream REST requests are HTTP requests as defined in RFC 2616. (For more information, go to http://www.ietf.org/rfc/rfc2616.txt.) This section describes the structure of an Amazon AppStream REST request. For detailed descriptions of the resources and references of the API, see Resources.

A typical REST action consists of sending an HTTP request to Amazon AppStream and waiting for the response. Like any HTTP request, a REST request to Amazon AppStream contains a request method, a URI, request headers, and sometimes a query string or request body. The response contains an HTTP status code, response headers, and sometimes a response body.

Limits on Request Rates

Amazon AppStream limits the rate at which you can submit requests:

  • You can submit a maximum of two POSTs to the applications resource per second per AWS account.

  • You can submit a maximum of four POSTs to an application's sessions resource per second per AWS account.

If you submit requests at a faster rate, Amazon AppStream may respond with HTTP 429 errors as explained in API Error Codes (Client and Server Errors).

HTTP Header Contents

Amazon AppStream requires the following information in the headers of an HTTP request:

Host (Required)

The Amazon AppStream endpoint. This value must be https://appstream.us-east-1.amazonaws.com.

x-amz-date or Date (Required)

The date used to create the signature contained in the Authorization header. Specify the date in ISO 8601 standard format, in UTC time, as in the following example: X-Amz-Date: 20130613T203622Z.

You must include either x-amz-date or Date. (Some HTTP client libraries don't let you set the Date header). When an x-amz-date header is present, the system ignores any Date header when authenticating the request.

The time stamp must be within 15 minutes of the AWS system time when the request is received. If it isn't, the request fails with the RequestExpired error code to prevent someone else from replaying your requests.

Authorization (Required)

The information required for request authentication. For more information about constructing this header, see Signing Requests.

Content-Type (Conditional)

Specifies JSON and the version, for example, Content-Type: application/x-amz-json-1.0.

Condition: Required for PUT and POST requests.

Content-Length (Conditional)

Length of the message (without the headers) according to RFC 2616.

Condition: Required if the request body itself contains information (most toolkits add this header automatically).

The following are example headers for an HTTP request to entitle a new client session.

Copy
POST /applications/e407fbc8-5c27-48e6-9412-a876167546e8/sessions HTTP/1.1 host: appstream.us-east-1.amazonaws.com x-amz-date: 20120116T174952Z Authorization: AWS4-HMAC-SHA256 Credential=AccessKeyID/20120116/us-east-1/ets/aws4_request,SignedHeaders=host;x-amz-date;x-amz-target,Signature=145b1567ab3c50d929412f28f52c45dbf1e63ec5c66023d232a539a4afd11fd9 content-type: application/x-amz-json-1.0 content-length: 56 { "opaqueData": "TYtYS00MaWQ9Y2JmOmM4hhZWNS00MjJ" }

HTTP Request Body

Many Amazon AppStream API actions require you to include JSON-formatted data in the body of the request. The JSON conforms to the Amazon AppStream schema.

Note

JSON values in the request body are strings.

HTTP Responses

All Amazon AppStream API actions include JSON-formatted data in the response. The JSON conforms to the Amazon AppStream schema.

Note

JSON values in the response are strings.

Here are some important headers in the HTTP response and how you should handle them in your application, if applicable:

HTTP/1.1

This header is followed by a status code. Status code 200 indicates a successful operation. For information about error codes, see API Error Codes (Client and Server Errors).

Type: String

x-amzn-RequestId

A value created by Amazon AppStream that uniquely identifies your request, for example, K2QH8DNOU907N97FNA2GDLL8OBVV4KQNSO5AEMVJF66Q9ASUAAJG. If you have a problem with Amazon AppStream, AWS can use this value to troubleshoot the problem. We recommend that you log these values.

Type: String

Content-Length

The length of the response body in bytes.

Type: String

Content-Type

The type of the message's content. Usually application/hal+json.

Type: String

Date

The date and time that Amazon AppStream responded, for example, Sun, 25 Mar 2012 12:00:00 GMT. The format of the date must be one of the full date formats specified by RFC 2616, section 3.3.

Type: String