Creating a private API in Amazon API Gateway - Amazon API Gateway

Creating a private API in Amazon API Gateway

Using Amazon API Gateway, you can create private REST APIs that can only be accessed from your virtual private cloud in Amazon VPC by using an interface VPC endpoint. This is an endpoint network interface that you create in your VPC.

Using resource policies, you can allow or deny access to your API from selected VPCs and VPC endpoints, including across AWS accounts. Each endpoint can be used to access multiple private APIs. You can also use AWS Direct Connect to establish a connection from an on-premises network to Amazon VPC and access your private API over that connection.

Important

To restrict access to your private API to specific VPCs or VPC endpoints, add aws:SourceVpc or aws:SourceVpce conditions to your API's resource policy. For example policies, see Example: Allow private API traffic based on source VPC or VPC endpoint.

In all cases, traffic to your private API uses secure connections and does not leave the Amazon network—it is isolated from the public internet.

You can access your private APIs through interface VPC endpoints for API Gateway as shown in the following diagram. If you have private DNS enabled, you can use private or public DNS names to access your APIs. If you have private DNS disabled, you can only use public DNS names.

Note

API Gateway private APIs only support TLS 1.2. Earlier TLS versions are not supported.


            Accessing private API with private DNS enabled

At a high level, the steps for creating a private API are as follows:

  1. First, create an interface VPC endpoint for the API Gateway component service for API execution, known as execute-api, in your VPC.

  2. Create and test your private API.

    1. Use one of the following procedures to create your API:

    2. To grant access to your VPC endpoint, create a resource policy and attach it to your API.

    3. Test your API.

Note

The procedures below assume you already have a fully configured VPC. For more information, and to get started with creating a VPC, see Getting Started With Amazon VPC in the Amazon VPC User Guide.

Private API development considerations

  • You can convert an existing public API (Regional or edge-optimized) to a private API, and you can convert a private API to a Regional API. You cannot convert a private API to an edge-optimized API. For more information, see Change a public or private API endpoint type in API Gateway.

  • To grant access to your private API to VPCs and VPC endpoints, you need to create a resource policy and attach it to the newly created (or converted) API. Until you do so, all calls to the API will fail. For more information, see Set up a resource policy for a private API.

  • Custom domain names are not supported for private APIs.

  • You can use a single VPC endpoint to access multiple private APIs.

  • You can associate or disassociate a VPC endpoint to a REST API, which gives a Route 53 alias DNS record and simplifies invoking your private API. For more information, see Associate or Disassociate a VPC Endpoint with a Private REST API.

Note

VPC endpoints for private APIs are subject to the same limitations as other interface VPC endpoints. For more information, see Interface Endpoint Properties and Limitations in the AWS PrivateLink Guide. For more information about using API Gateway with shared VPCs and shared subnets, see Shared subnets in the AWS PrivateLink Guide.

Create an interface VPC endpoint for API Gateway execute-api

The API Gateway component service for API execution is called execute-api. To access your private API once it's deployed, you need to create an interface VPC endpoint for it in your VPC.

After you've created your VPC endpoint, you can use it to access multiple private APIs.

To create an interface VPC endpoint for API Gateway execute-api
  1. Sign in to the AWS Management Console and open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoints, Create Endpoint.

  3. For Service category, ensure that AWS services is selected.

  4. For Service Name, choose the API Gateway service endpoint, including the AWS Region that you want to connect to. This is in the form com.amazonaws.region.execute-api—for example, com.amazonaws.us-east-1.execute-api.

    For Type, ensure that it indicates Interface.

  5. Complete the following information:

    • For VPC, choose the VPC that you want to create the endpoint in.

    • For Subnets, choose the subnets (Availability Zones) in which to create the endpoint network interfaces. To improve the availability of your API, choose multiple subnets.

      Note

      Not all Availability Zones may be supported for all AWS services.

    • For Enable Private DNS Name, leave the check box selected. Private DNS is enabled by default.

      When private DNS is enabled, you're able to access your API via private or public DNS. (This setting doesn't affect who can access your API, only which DNS addresses they can use.) However, you cannot access public APIs from a VPC by using an API Gateway VPC endpoint with private DNS enabled. Note that these DNS settings don't affect the ability to call these public APIs from the VPC if you're using an edge-optimized custom domain name to access the public API. Using an edge-optimized custom domain name to access your public API (while using private DNS to access your private API) is one way to access both public and private APIs from a VPC where the endpoint has been created with private DNS enabled.

      Note

      Leaving private DNS enabled is the recommended choice. If you choose not to enable private DNS, you're only able to access your API via public DNS. To learn more, see How to invoke a private API.

      To use the private DNS option, the enableDnsSupport and enableDnsHostnames attributes of your VPC must be set to true. For more information, see DNS Support in Your VPC and Updating DNS Support for Your VPC in the Amazon VPC User Guide.

    • For Security group, select the security group to associate with the VPC endpoint network interfaces.

      The security group you choose must be set to allow TCP Port 443 inbound HTTPS traffic from either an IP range in your VPC or another security group in your VPC.

  6. Choose Create endpoint.

Create a private API using the API Gateway console

To create a private API using the API Gateway console
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose Create API.

  3. Under REST API, choose Build.

  4. For Name, enter a name.

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

  6. For API endpoint type, select Private.

  7. Choose Create API.

From here on, you can set up API methods and their associated integrations as described in steps 1-6 of Create an API with HTTP custom integration.

Note

Until your API has a resource policy that grants access to your VPC or VPC endpoint, all API calls will fail. Before you test and deploy your API, you need to create a resource policy and attach it to the API as described in Set up a resource policy for a private API.

Create a private API using the AWS CLI

To create a private API using the AWS CLI, call the create-rest-api command:

aws apigateway create-rest-api \ --name 'Simple PetStore (AWS CLI, Private)' \ --description 'Simple private PetStore API' \ --region us-west-2 \ --endpoint-configuration '{ "types": ["PRIVATE"] }'

A successful call returns output similar to the following:

{ "createdDate": "2017-10-13T18:41:39Z", "description": "Simple private PetStore API", "endpointConfiguration": { "types": "PRIVATE" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (AWS CLI, Private)" }

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.

When you are ready to test your API, be sure to create a resource policy and attach it to the API as described in Set up a resource policy for a private API.

Create a private API using the AWS SDK for JavaScript

To create a private API by using the AWS SDK for JavaScript:

apig.createRestApi({ name: "Simple PetStore (node.js SDK, private)", endpointConfiguration: { types: ['PRIVATE'] }, description: "Demo private 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 call returns output similar to the following:

{ "createdDate": "2017-10-13T18:41:39Z", "description": "Demo private API created using the AWS SDK for node.js", "endpointConfiguration": { "types": "PRIVATE" }, "id": "0qzs2sy7bh", "name": "Simple PetStore (node.js SDK, private)" }

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.

When you are ready to test your API, be sure to create a resource policy and attach it to the API as described in Set up a resource policy for a private API.

Set up a resource policy for a private API

Before your private API can be accessed, you need to create a resource policy and attach it to the API. This grants access to the API from your VPCs and VPC endpoints or from VPCs and VPC endpoints in other AWS accounts that you explicitly grant access.

To do this, follow the instructions in Create and attach an API Gateway resource policy to an API. In step 5, choose the Source VPC example. Replace {{vpceID}} (including the curly braces) with your VPC endpoint ID, and then choose Save to save your resource policy.

You should also consider attaching an endpoint policy to the VPC endpoint to specify the access that's being granted. For more information, see Use VPC endpoint policies for private APIs in API Gateway.

Deploy a private API using the API Gateway console

To deploy your private API, do the following in the API Gateway console:

  1. Choose your API.

  2. Choose Deploy API.

  3. For Stage, select New stage.

  4. For Stage name, enter a stage name.

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

  6. Choose Deploy.

Associate or disassociate a VPC endpoint with a private REST API

When you associate a VPC endpoint with your private API, API Gateway generates a new Route 53 ALIAS DNS record. You can use this record to invoke your private APIs just as you do your edge-optimized or Regional APIs without overriding a Host header or passing an x-apigw-api-id header.

The generated base URL is in the following format:

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

Associating or disassociating a VPC endpoint with a private REST API requires you to update the API's configuration. You can perform this change using the API Gateway console, the AWS CLI, or an AWS SDK for API Gateway. The update operation may take few minutes to complete due to DNS propagation. During this time, your API is available, but DNS propagation for the newly generated DNS URLs may still be in progress. You may try creating a new deployment for your API, if even after several minutes your new URLs are not resolving in DNS.

Use the API Gateway console to associate a VPC endpoint with a private REST API

To associate an additional VPC endpoint with a private API
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose your private API.

  3. In the main navigation pane, choose Resource policy.

  4. Edit your resource policy to allow calls from your additional VPC endpoint.

  5. In the main navigation pane, choose API settings.

  6. In the API details section, choose Edit.

  7. For VPC endpoint IDs, select additional VPC endpoint IDs.

  8. Choose Save.

  9. Redeploy your API for the changes to take effect.

Use the AWS CLI to associate a VPC endpoint with a private REST API

To associate VPC endpoints at the time of API creation, use the following command:

aws apigateway create-rest-api \ --name Petstore \ --endpoint-configuration '{ "types": ["PRIVATE"], "vpcEndpointIds" : ["vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee"] }' \ --region us-west-2

The output will look like the following:

{ "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "PRIVATE" ], "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee" ] }, "id": "u67n3ov968", "createdDate": 1565718256, "name": "Petstore" }

To associate VPC endpoints to an already created private API, use the following CLI command:

aws apigateway update-rest-api \ --rest-api-id u67n3ov968 \ --patch-operations "op='add',path='/endpointConfiguration/vpcEndpointIds',value='vpce-01d622316a7df47f9'" \ --region us-west-2

The output will look like the following:

{ "name": "Petstore", "apiKeySource": "1565718256", "tags": {}, "createdDate": 1565718256, "endpointConfiguration": { "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-0393a628149c867ee", "vpce-01d622316a7df47f9" ], "types": [ "PRIVATE" ] }, "id": "u67n3ov968" }

Use the API Gateway console to disassociate a VPC endpoint from a private REST API

To disassociate a VPC endpoint from a private REST API
  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose your private API.

  3. In the main navigation pane, choose Resource policy.

  4. Edit your resource policy to remove mentions of the VPC endpoint you want to dissociate from your private API.

  5. In the main navigation pane, choose API settings.

  6. In the API details section, choose Edit.

  7. For VPC endpoint IDs, choose the X to dissociate the VPC endpoint.

  8. Choose Save.

  9. Redeploy your API for the changes to take effect.

Use the AWS CLI to disassociate a VPC endpoint from a private REST API

To disassociate a VPC endpoint from a private API, use the following CLI command:

aws apigateway update-rest-api \ --rest-api-id u67n3ov968 \ --patch-operations "op='remove',path='/endpointConfiguration/vpcEndpointIds',value='vpce-0393a628149c867ee'" \ --region us-west-2

The output will look like the following:

{ "name": "Petstore", "apiKeySource": "1565718256", "tags": {}, "createdDate": 1565718256, "endpointConfiguration": { "vpcEndpointIds": [ "vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9" ], "types": [ "PRIVATE" ] }, "id": "u67n3ov968" }