Amazon API Gateway REST API Reference

Making HTTP Requests to Amazon API Gateway

Amazon API Gateway REST requests are HTTP requests as defined in RFC 2616. (For more information, go to This section describes the structure of an Amazon API Gateway 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 API Gateway and waiting for the response. Like any HTTP request, a REST request to Amazon API Gateway 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

For limits on individual request rates, see API Gateway Limits

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

HTTP Request URL

The URL of an API Gateway API request has the following format:


where {path} is the URL path of an API Gateway resource or link-relation. For example, to view the API collections in your account, you will submit the following request on the RestApis resource:

GET https://apigateway.{region} HTTP/1.1
Authorization: ...

Here, the Authorization header containing your credentials is used to identify your account. The URL path for the this request is 'restapis'.

To add a GET method on a resource ({resource_id}) of an API ({restapi_id}), you will call the method:put link-relation, as shown as follows:

PUT https://apigateway.{region}{restapi_id}/resources/{resource_id}/methods/GET
Content-Type: application/json
Content-Length: ...
Authorization: ...

  "authorizationType" : "String",
  "authorizerId" : "String",
  "apiKeyRequired" : "Boolean",
  "requestParameters" : {
    "String" : "Boolean"
  "requestModels" : {
    "String" : "String"

The URL path for the this request is 'restapis/{restapi_id}/resources/{resource_id}/methods/GET'.

HTTP request query parameters

When a query parameter is a list type, its value must be a string of comma-separated items. For example, GET /restapis/restapi_id/deployments/deployment_id?embed=apisummary,sdksummary.

Amazon API Gateway does not support nested query parameters of the form: GET /team?user[id]=usrid on a method request. You could work around this limitation by passing an encoded map as a single parameter and serializing it as part of a mapping template or in your back-end integration.

HTTP Header Contents

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

Host (Required)

The Amazon API Gateway endpoint. This value must be one of the region-dependent endpoints listed under Regions and Endpoints. In the US East (N. Virginia) region, it is

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.

POST /restapis/e407fbc8-5c27-48e6-9412-a876167546e8/sessions HTTP/1.1
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 API Gateway API actions require you to include JSON-formatted data in the body of the request. The JSON conforms to the Amazon API Gateway schema.


JSON values in the request body are strings.

HTTP Responses

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


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:


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


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

Type: String


The length of the response body in bytes.

Type: String


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

Type: String


The date and time that Amazon API Gateway 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