Set up a Regional API in API Gateway - Amazon API Gateway

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.

Note

In cases where API clients are geographically dispersed, it may still make sense to use a Regional API endpoint, together with your own Amazon CloudFront distribution to ensure that API Gateway does not associate the API with service-controlled CloudFront distributions. For more information about this use case, see How do I set up API Gateway with my own CloudFront distribution?.

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, and the AWS SDK for Javascript for Node.js.

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 at https://console.aws.amazon.com/apigateway.

  2. Do one of the following:

    • To create your first API, for REST API, choose Build.

    • If you've created an API before, choose Create API, and then choose Build for REST API.

  3. For Name, enter a name.

  4. (Optional) For Description, enter a description.

  5. Keep API endpoint type set to Regional.

  6. Choose Create 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 an OpenAPI definition

To import an API from an OpenAPI definition file using the AWS CLI, use the import-rest-api command:

aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json'

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