Rest API - Best Practices for Designing Amazon API Gateway Private APIs and Private Integration

Rest API

REST APIs help create APIs that follow the REST architectural style. Developers can use their existing knowledge and apply best practices while building REST APIs in API Gateway.

While designing a REST API, a key consideration is security. Use least privilege access when giving access to APIs. The private endpoint type restricts API access through interface VPC endpoints only. If REST APIs are publicly exposed but integration endpoints exist in a private subnet, private integration offers a way to access the endpoints via a VPC link. You can create a VPC link with a Network Load Balancer. API Gateway creates a VPC endpoint service for API Gateway to access Network Load Balancer.

Private Endpoint Type

To make APIs accessible only from Amazon VPCs, you can use REST APIs with the private endpoint type. The traffic to the APIs will not leave the AWS network. There are three options to invoke a private API through different domain name system (DNS) names:

  • Private DNS names

  • Interface VPC endpoint public DNS hostnames

  • Amazon Route53 alias

While configuring private APIs, there are several key points to consider. The “DNS Names for Private APIs” section provides use cases, pros, and cons about each option.

DNS Names for Private APIs

Table 1 – Private API DNS names

DNS names Private DNS option on VPCe Pros Cons
Private DNS names Enabled Easy to set up DNS issue with regional and edge-optimized APIs.
Interface VPC endpoint public DNS hostnames Disabled The domain name is publicly resolvable. Requires a Host or x-apigw-api-id header in requests.
Route53 alias Disabled

The domain name is publicly resolvable.

The host or x-apigw-api-id header is not required.

Requires an interface VPC endpoint association with each private API.

Private DNS Names

This option works when the private DNS option on an interface VPC endpoint is enabled. In addition, to resolve the name, AmazonProvidedDNS should be present in the DHCP options set for the clients in the VPC. Because those are the only requirements, this option is usually easy to use for a simple use case such as invoking a private API within a VPC.

However, if you use a custom DNS server, a conditional forwarder must be set on the DNS that points to the AmazonProvidedDNS or Route53 Resolver. Because of the private DNS option enabled on the interface VPC endpoint, DNS queries against *.execute-api.amazonaws.com will be resolved to private IPs of the endpoint. This causes issues when clients in the VPC try to invoke regional or edge-optimized APIs, because those types of APIs must be accessed over the internet. Traffic through interface VPC endpoints is not allowed. The only workaround is to use an edge-optimized custom domain name. See Why do I get an HTTP 403 Forbidden error when connecting to my API Gateway APIs from a VPC? for the troubleshooting steps.

VPC Endpoint Public DNS Hostnames

If your use case requires the private DNS option to be disabled, consider using interface VPC endpoint public DNS hostnames. When you create an interface VPC endpoint, it also generates the public DNS hostname. When invoking a private API through the hostname, you must pass a Host or x-apigw-api-id header.

The header requirement can cause issues when the hostname is used in a web application. For cross-origin, non-simple requests, modern browsers send a preflight request to an endpoint. This option requires clients to send requests with a custom header. Because browsers will not send the custom header for the preflight request, this will cause CORS issues. This option is not a preferred option for customers who need to use a private API from a web application.

Route 53 Alias

This Route 53 option resolves the header requirement imposed by the VPC endpoint public DNS hostnames option. Additionally, the Route 53 alias is publicly resolvable, and does not require private DNS to be enabled. Clients in a VPC can access private APIs through the Route 53 alias, as well as other types of APIs such as regional and edge-optimized REST APIs.

Each alias is generated after associating a VPC endpoint to a private API. The association is required every time you create new interface VPC endpoints and private APIs.

Resource-Based Policy

Resource-based policies are attached to a resource like a REST API in API Gateway. For resource-based policies, you can specify who has access to the resource and what actions are permitted.

Unlike regional and edge-optimized endpoint types, private APIs require the use of a resource policy. Deployments without a resource policy will fail. For private APIs, there are additional keys within the condition block you can use in the resource policy, such as aws:sourceVpc and aws:SourceVpce. The aws:sourceVpc policy allows traffic to originate from specific VPCs, and aws:SourceVpce allows traffic originating from interface VPC endpoints.

Private Integration

Private integrations allow routing traffic from API Gateway to customers’ VPCs. The integrations are based on VPC links, and rely on a VPC endpoint service that is tied to network load balancers (NLBs) for REST and WebSocket APIs. VPC link integrations work in a similar way as HTTP integrations. A common use case is to invoke Amazon EC2-hosted applications behind NLBs through VPC links. There are several design considerations in this case:

  • For existing applications with a Classic Load Balancer (CLB) or Application Load Balancer (ALB:

    • Create an NLB in front of a CLB or ALB.

      • This creates an additional network hop and infrastructure cost.

    • Route traffic through NLB instead of CLB or ALB.

      • This requires migration from CLB or ALB to NLB to shift traffic and redesign the existing architecture. See Migrate your Classic Load Balancer for the migration process.

  • NLB listener type

    • Transmission control protocol (TCP) (Secure Socket Layer (SSL) passthrough or non-SSL traffic)

    • Transport Layer Security (TLS) (terminating the SSL connection on NLB)

Sample Architecture Patterns

When implementing a private API, using an authorizer such as AWS Identity and Access Management (IAM) or Amazon Cognito is highly recommended. This ensures an additional layer of security, and helps verify requests using IAM credentials for IAM authorization, and access/ID tokens for the Amazon Cognito authorizer.

Basic Architecture

In the basic architecture, Amazon EC2 instances and VPC-enabled AWS Lambda functions access a private API through an interface VPC endpoint. The security group attached to the endpoint must allow the Transmission Control Protocol (TCP) port 443. In the private API resource policy, requests from the VPC and interface VPC endpoint should be allowed.


          Architectural diagram showing basic REST private API architecture

Figure 1 – REST private API basic architecture

Cross-Account Architecture

If you want to allow access to a private API from other accounts, an interface VPC endpoint in a different account can be used to invoke the API. However, they both must exist in the same Region, such as us-east-1 (N. Virginia). Additionally, the private API resource policy must allow access from the other account’s VPC or interface VPC endpoint.


          Architecture diagram showing REST private API cross-account architecture

Figure 2 – REST private API cross-account architecture

On-Premises Architecture

If you have users accessing from on-premises locations, you will need a Direct Connect or VPN connection between the on-premises networks and your VPC. All requests must still go through interface VPC endpoints. For the on-premises architecture, VPC endpoint public DNS hostnames or Route 53 alias records are good options when invoking private APIs. If on-premises users access the network through a web application, Route 53 alias records are a better approach to avoid CORS issues. If the Route 53 alias record option does not work, one solution is to create a conditional forwarder on an on-premises DNS pointing to a Route 53 resolver. See Resolving DNS queries between VPCs and your network.

The following diagram shows a sample architecture where on-premises clients access a web application hosted in the on-premises network. The web application uses a private API for its API endpoint. For the private API endpoint, a Route 53 alias is used. Because a Route 53 alias record is publicly resolvable, there is no need to set up a conditional forwarder on on-premises DNS servers to resolve the hostname.


          Architecture diagram showing REST private API on-premises architecture

Figure 3 – REST private API on-premises architecture

Private Integration Architecture with ECS

Amazon Elastic Container Service (Amazon ECS) is a fully managed container orchestration service. Customers can use ECS to run their most sensitive and mission critical applications because of its security, reliability, and scalability. For private integration in REST APIs, one common design pattern is to use an NLB to route traffic to an Amazon ECS cluster in private subnets. Many customers deploy ECS as their backend compute service. The following diagram shows clients in one VPC accessing an ECS cluster in another VPC through a private API and private integration.


          Architecture diagram showing Cross-VPC ECS access via Private Integration with
            Private API

Figure 4 – Cross-VPC ECS Access via Private Integration with Private API