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 https://www.w3.org/Protocols/rfc2616/rfc2616.html.) 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, against a resource following a link-relation, and waiting for the response. Like any HTTP request, a REST request to Amazon API Gateway contains a request method, a resource URI, request headers, and any applicable query strings or request body. The response contains an HTTP status code, response headers, and any applicable response body.

HTTP Request URL

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

https://apigateway.{region}.amazonaws.com/{path}

where {path} identifies an API Gateway resource of a given hierarchy under the root resource (/). For example, to view the API collections in your account, submit the following request against the RestApis resource, following the apigateway:rest-apis link relation:

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

The Authorization header containing the caller's credentials is used to sign the request for Amazon API Gateway to authenticate the caller and to authorize the request according to pre-configured AWS IAM roles or policies. The URL path for the this request is /restapis.

To add a GET method on a resource ({resource_id}) of an API ({restapi_id}), follow the method:put link-relation to make the following call:

PUT https://apigateway.{region}.amazonaws.com/restapis/{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 apigateway.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 payload-less methods, such as GET, the SignedHeaders string, used to sign the request using Signature Version 4, must include host;x-amz-date. For method requiring payloads, such as POST, the SignedHeaders string must also include content-type. Unlike other AWS services, such as DynamoDB, the x-amz-target header is not required to compute the Authorization header value. 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 PATCH, 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 example shows typical headers for an HTTP request to create a new API.

POST /restapis HTTP/1.1
host: apigateway.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,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.

Note

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.

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

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

Request Rate Limits

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