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


HTTP API is a new flavor of API Gateway. Benefits of using the API include delivering enhanced features, improved performance, and an easier developer experience. In addition, HTTP APIs come with reduced request pricing.

For private integrations, HTTP APIs offer additional integration endpoints for a VPC link, such as ALBs, NLBs, and AWS Cloud Map. For any existing applications or micro services that have ALBs or AWS Cloud Map to route traffic, you can use the same setup. HTTP APIs can route traffic to those endpoints through a VPC link.

Private integration

Because HTTP APIs offer three different private integration targets, you should consider which integration target best suits your use case. Depending on the backend service, one or more targets can be used by creating multiple VPC endpoints.

Table 2 – HTTP API private integration

Integration target Listener Use cases
NLB TCP or TLS listener

TLS passthrough is possible

High throughput

ALB HTTP or HTTPS listener

Layer 7 routing

Content-based routing

AWS Cloud Map


AWS Cloud Map parameters (optional)

Service discovery

Sample architecture patterns

ALB architecture (ECS)

HTTP API private integration allows NLB and ALB for integration targets for load balancers. If you have any backend service fronted with ALBs, you can use the existing setup without re-architecting. Because ALBs allow different routing options, such as path-based routing, this option provides flexibility on the ALB routing level. To create listener rules to achieve path-based routing, refer to Listener rules for your Application Load Balancer.

The following figure shows private integration with ALB in HTTP API. The ALB uses path-based routing rules to route traffic to two different ECS services.

A diagram that shows HTTP API private integration with ALB.

HTTP API private integration with ALB

Cloud Map architecture (microservices)

With the AWS Cloud Map target option, you can use AWS Cloud Map to discover services like ECS and EC2-based services. Using AWS Cloud Map as a front-end service for microservices, you can leverage a private integration with an AWS Cloud Map target in HTTP APIs to route requests to different endpoints.

A diagram that shows HTTP API private integration with Cloud Map.

HTTP API private integration with Cloud Map

Private integration cross-account

For cross-account access of private resources with HTTP APIs the architecture is very similar to that of REST APIs. The difference is you now have the choice of ALB, NLB or AWS Cloud Map for the VPC Link, rather than just an NLB. 

In the sample architecture below AWS PrivateLink is used to access resources in another AWS account. The VPC link must exist in the same account as the API Gateway. The Application Load Balancer used in this VPC link is pointing to the VPC endpoint private IP addresses of the PrivateLink connection.

A diagram that shows HTTP private cross-account integration using AWS PrivateLink

HTTP private cross-account integration using AWS PrivateLink

For more detail on the above architecture and to deploy a code example, refer to Building private cross-account APIs using Amazon API Gateway and AWS PrivateLink.

With HTTP APIs, you can also use AWS Cloud Map to create a VPC link connection. In the following sample architecture, AWS Cloud Map is used to resolve private resources in another AWS account. The central API Gateway account and the resource account VPCs are connected using AWS Transit Gateway VPC attachments to provide private routing. Transit Gateway is an alternative to using VPC peering by providing a hub and spoke network design.

A document that shows HTTP private cross-account integration using AWS Cloud Map and AWS Transit Gateway.

HTTP private cross-account integration using AWS Cloud Map and AWS Transit Gateway


AWS Cloud Map integration using Amazon ECS service discovery does not support cross-account patterns. To implement the architecture shown in the previous diagram, you must register cross-account ECS resources manually in the AWS Cloud Map namespace.