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

How to invoke a private API

Private APIs are accessible only from within your VPCs, and the resource policies must allow access from the VPCs and VPC endpoints you have configured. How you access your private API will depend upon whether or not you have enabled private DNS on the VPC endpoint. For example, while accessing private API from on-premises network via Amazon Direct Connect, you will have private DNS enabled on the VPC endpoint. In such a case, follow the steps outlined in Invoking Your Private API Using Endpoint-Specific Public DNS Hostnames.

Once you have deployed a private API, you can access it via private DNS (if you've enabled private DNS naming) and via public DNS.

To get the DNS names for your private API, do the following:

Invoking your private API using private DNS names

If you've enabled private DNS, you can access your private API using the private DNS names as follows:

{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, assuming you set up the GET /pets and GET /pets/{petId} methods in this example, and assuming that your rest API ID was 01234567ab and your region was us-west-2, you could test your API by typing the following URLs in a browser:

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

and

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

Alternatively, you could use the following cURL commands:

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

and

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

Accessing your private API using Amazon Direct Connect

You can also 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.

Accessing your private API using a Route53 alias

You can associate or disassociate a VPC endpoint with your private API by using the procedure outlined in Associate or Disassociate a VPC Endpoint with a Private REST API.

Once you associate your private API's REST API ID with the VPC endpoints you'll be calling your REST API from, you can use the following format base URL to invoke the API using a Route53 alias.

The generated base URL is in the following format:

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

For example, assuming you set up the GET /pets and GET /pets/{petId} methods in this example, and assuming that your API's API ID was 01234567ab, 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/

Invoking your 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, assuming you set up the GET /pets and GET /pets/{petId} methods in this example, and assuming that your API's API ID was abc1234, its public DNS hostname was vpce-def-01234567, and your Region was us-west-2, you could test your API via its VPCE ID by using the Host header in a cURL command, as in the following example:

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 access 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/test -H'x-apigw-api-id:{api-id}'