Call a private API - Amazon API Gateway
Invoke a private API using a Route53 aliasInvoke a private API using private DNS namesInvoke a private API using Amazon Direct ConnectInvoke a private API using endpoint-specific public DNS hostnames
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Call a private API

You can only invoke a private API from within a VPC. Your private API must have a resource policy that allows specific VPCs and VPC endpoints to invoke your API.

You can invoke your private API in the following ways.

  • Invoke your API using a Route53 alias. This is only available if you associated your VPC endpoint with your API. For more information, see (Optional) Associate or disassociate a VPC endpoint with a private API.

  • Invoke your API using private DNS. This is only available if you enabled private DNS for your VPC.

  • Invoke your API using Amazon Direct Connect.

  • Invoke your API using endpoint-specific public DNS hostnames.

To invoke your private API using a DNS name, you need to identify the DNS names for your API. The following procedure shows how to find your DNS names.

Amazon Web Services Management Console
To find the DNS names

  1. Sign in to the Amazon Web Services Management Console and open the Amazon VPC console at https://console.amazonaws.cn/vpc/.

  2. In the main navigation pane, choose Endpoints and then choose your interface VPC endpoint for API Gateway.

  3. In the Details pane, you'll see five values in the DNS names field. The first three are the public DNS names for your API. The other two are the private DNS names for it.

Amazon CLI

Use the following describe-vpc-endpoints command to list your DNS values.

aws ec2 describe-vpc-endpoints --filters vpc-endpoint-id=vpce-01234567abcdef012

The first three are the public DNS names for your API. The other two are the private DNS names for it.

Invoke a private API using a Route53 alias

You can associate or disassociate a VPC endpoint with your private API. For more information, see (Optional) Associate or disassociate a VPC endpoint with a private API.

After you associate your VPC endpoints with your private API, you can use the following base URL to invoke the API:

https://{rest-api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage}

For example, if you set up the GET /pets method for the test stage, and your REST API ID was 01234567ab, and your VPC endpoint ID was vpce-01234567abcdef012, and your Region was us-west-2, you can invoke your API as:

curl -v https://01234567ab-vpce-01234567abcdef012.execute-api.us-west-2.amazonaws.com/test/pets

Invoke a private API using private DNS names

If you've enabled private DNS, you can access your private API using the following private DNS name:

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

The base URL to invoke the API is in the following format:

https://{restapi-id}.execute-api.{region}.amazonaws.com/{stage}

For example, if you set up the GET /pets method for the test stage, and your REST API ID was 01234567ab and your Region was us-west-2, you could invoke your private API by entering the following URL in a browser:

https://01234567ab.execute-api.us-west-2.amazonaws.com/test/pets

Alternatively, you could use the following cURL command to invoke your private API:

curl -X GET https://01234567ab.execute-api.us-west-2.amazonaws.com/test/pets
Warning

If you enable private DNS for your VPC endpoint, you won't be able to access the default endpoint for public APIs. For more information, see Why can't I connect to my public API from an API Gateway VPC endpoint?.

Invoke a private API using Amazon Direct Connect

You can use Amazon Direct Connect to establish a dedicated private connection from an on-premises network to Amazon VPC and access your private API endpoint over that connection by using public DNS names.

You can also use private DNS names to access your private API from an on-premises network by setting up an Amazon Route 53 Resolver inbound endpoint and forwarding it all DNS queries of the private DNS from your remote network. For more information, see Forwarding inbound DNS queries to your VPCs in the Amazon Route 53 Developer Guide.

Invoke a private API using endpoint-specific public DNS hostnames

You can access your private API using endpoint-specific DNS hostnames. These are public DNS hostnames containing the VPC endpoint ID or API ID for your private API.

The generated base URL is in the following format:

https://{public-dns-hostname}.execute-api.{region}.vpce.amazonaws.com/{stage}

For example, if you set up the GET /pets method for the test stage, and your REST API ID was abc1234, its public DNS hostname was vpce-def-01234567, and your Region was us-west-2, you could invoke your private API using its VPCe ID by using the Host header in a cURL command:

curl -v https://vpce-def-01234567.execute-api.us-west-2.vpce.amazonaws.com/test/pets -H 'Host: abc1234.execute-api.us-west-2.amazonaws.com'

Alternatively, you can invoke your private API via its API ID by using the x-apigw-api-id header in a cURL command in the following format:

curl -v https://{public-dns-hostname}.execute-api.{region}.vpce.amazonaws.com/{stage} -H 'x-apigw-api-id:{api-id}'