Set up a Regional API in API Gateway
When API requests predominantly originate from an EC2 instance or services within the same region as the API is deployed, a regional API endpoint will typically lower the latency of connections and is recommended for such scenarios. In addition, for customers to manage their own Amazon CloudFront distribution, they can use a regional API endpoint to ensure that API Gateway does not associate the API with the service-controlled CloudFront distributions.
To create a regional API, you follow the steps in creating an edge-optimized API, but must
explicitly set REGIONAL
type as the only option of the API's endpointConfiguration.
In the following, we show how to create a regional API using the API Gateway console, AWS CLI, the AWS SDK for Javascript for Node.js, and the API Gateway REST API.
Topics
Create a Regional API Using the API Gateway Console
To create a regional API using the API Gateway console
-
Sign in to the API Gateway console and choose + Create API.
-
Under Create new API, choose the New API option.
-
Type a name (for example,
Simple PetStore (Console, Regional)
) for API name. -
Choose
Regional
for Endpoint Type. -
Choose Create API.
From here on, you can proceed to set up API methods and their associated integrations as described in creating an edge optimized API.
Create a Regional API Using the AWS CLI
To create a regional API using the AWS CLI, call the create-rest-api
command:
aws apigateway create-rest-api \ --name 'Simple PetStore (AWS CLI, Regional)' \ --description 'Simple regional PetStore API' \ --region us-west-2 \ --endpoint-configuration '{ "types": ["REGIONAL"] }'
A successful response returns a payload similar to the following:
{ "createdDate": "2017-10-13T18:41:39Z", "description": "Simple regional PetStore API", "endpointConfiguration": { "types": "REGIONAL" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (AWS CLI, Regional)" }
From here on, you can follow the same instructions given in Set up an Edge-Optimized API Using AWS CLI Commands to set up methods and integrations for this API.
Create a Regional API Using the AWS SDK for JavaScript
To create a regional API, using the AWS SDK for JavaScript:
apig.createRestApi({ name: "Simple PetStore (node.js SDK, regional)", endpointConfiguration: { types: ['REGIONAL'] }, description: "Demo regional API created using the AWS SDK for node.js", version: "0.00.001" }, function(err, data){ if (!err) { console.log('Create API succeeded:\n', data); restApiId = data.id; } else { console.log('Create API failed:\n', err); } });
A successful response returns a payload similar to the following:
{ "createdDate": "2017-10-13T18:41:39Z", "description": "Demo regional API created using the AWS SDK for node.js", "endpointConfiguration": { "types": "REGIONAL" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (node.js SDK, regional)" }
After completing the preceding steps, you can follow the instructions in Set up an Edge-Optimized API Using the AWS SDK for Node.js to set up methods and integrations for this API.
Create a Regional API Using the API Gateway REST API
To create a regional API using the API Gateway REST API, submit a POST request as follows:
POST /restapis HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170511T214723Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170511/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=d0abd98a2a06199531c2916b162ede9f63a247032cdc8e4d077216446d13103c { "name": "Simple PetStore (REST API, Regional)", "description": "A sample API Gateway API created using the REST API.", "endpointConfiguration" : { "types" : ["REGIONAL"] } }
A successful response has a status code of 201 Created
and a body
similar to the following:
{ "createdDate": "2017-10-13T18:41:39Z", "description": "A sample API Gateway API created using the REST API.", "endpointConfiguration": { "types": "REGIONAL" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (REST API, Regional)" }
After completing the preceding steps, you can follow the instructions in Set up an Edge-Optimized API Using the API Gateway REST API to set up methods and integrations for this API.
Test a Regional API
Once deployed, the regional API's default URL host name is of the following format:
{restapi-id}
.execute-api.{region}
.amazonaws.com
The base URL to invoke the API is like the following:
https://
{restapi-id}
.execute-api.{region}
.amazonaws.com/{stage}
Assuming you set up the GET /pets
and GET /pets/{petId}
methods in this example, you can test the API by typing the following URLs in a
browser:
https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets
and
https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets/1
Alternatively, you can use cURL commands:
curl -X GET https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets
and
curl -X GET https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets/2