Menu
Amazon API Gateway
Developer Guide

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.

Create a Regional API Using the API Gateway Console

To create a regional API using the API Gateway console

  1. Sign in to the API Gateway console and choose + Create API.

  2. Under Create new API, choose the New API option.

  3. Type a name (for example, Simple PetStore (Console, Regional)) for API name.

  4. Choose Regional for Endpoint Type.

  5. 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:

Copy
aws apigateway create-rest-api \ --name 'Simple PetStore (AWS CLI, Regional)' \ --description 'Simple regional PetStore API' \ --region us-west-2 \ --endpointConfiguration '{ types: ["REGIONAL"] }'

The successful response returns an output similar to the following:

Copy
{ "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:

Copy
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); } });

The successful response returns an output similar to the following:

Copy
{ "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:

Copy
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"] } }

The successful response has the status code of 201 Created and a body similar to the following output:

Copy
{ "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:

Copy
{restapi-id}.execute-api.{region}.amazonaws.com

The base URL to invoke the API is like the following:

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

Copy
https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets

and

Copy
https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets/1

Alternatively, you can use cURL commands:

Copy
curl -X GET https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets

and

Copy
curl -X GET https://0qzs2sy7bh.execute-api.us-west-2.amazonaws.com/test/pets/2