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 through a VPC link. For REST APIs, VPC links V2 support both Application Load Balancer (ALB) and Network Load Balancer (NLB) as integration targets. VPC links V1 (NLB-only) are a legacy integration type. For more information, see Private integrations for REST APIs in API Gateway.

Private endpoint type

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

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.

IP address considerations

Private REST APIs only support dualstack (IPv4 and IPv6) IP address types. You cannot restrict a private API to accept only IPv4 traffic. When working with private APIs, consider the following:

For more information, see IP address types for REST APIs in API Gateway.

DNS names for private APIs

Table 1 – Private API DNS names

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. There are two workarounds: (1) use an edge-optimized custom domain name, or (2) turn off private DNS, create a private hosted zone for each private API in the VPC, and provision the required records in Route 53. This allows private APIs to resolve while still enabling invocation of public default endpoints from the VPC. See Why do I get an HTTP 403 Forbidden error when connecting to my API Gateway APIs from a VPC? on the AWS re:Post website for the troubleshooting steps.

Map a private REST API to a private custom domain name (for example, api.internal.example.com) backed by an AWS Certificate Manager (ACM) certificate. The consumer creates a domain name access association between a VPC endpoint and the custom domain, then resolves the name through a Route 53 private hosted zone. This option supports cross-account sharing through AWS RAM and routing rules for header/path-based traffic management. TLS is fixed at TLS-1-2. Wildcard custom domain names are not supported.

For more information, review the architecture patterns Cross-Account Architecture Using a Private Custom Domain Name and Multi-Region Private API Gateway using Private Custom Domains.

VPC endpoint public DNS hostnames

If your use case requires the private DNS option to be turned off, 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.

Amazon Route 53 alias

This Amazon 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. The resource policy must explicitly allow access from specific VPCs (using aws:sourceVpc) or VPC endpoints (using aws:sourceVpce). Without these conditions, API invocations will return 403 Forbidden errors. 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. If you use IP-based conditions such as aws:SourceIp, you must include both IPv4 and IPv6 CIDR ranges because private APIs only support dualstack.

Private integration

Private integrations allow routing traffic from API Gateway to resources within your VPCs. The integrations are based on VPC links, which encapsulate connections between API Gateway and targeted VPC resources.

VPC link types for REST APIs

API Gateway supports two types of VPC links for REST APIs:

For more information, see Private integrations for REST APIs in API Gateway

VPC link V2 operational considerations

The following considerations apply to all patterns that use VPC links V2:

Design considerations for private integration

With VPC links V2, you can now use ALB directly as an integration target for REST APIs, removing the need to place an NLB in front of an existing ALB.

NLB listener types include TCP (SSL passthrough or non-SSL traffic) and TLS (ending the SSL connection on NLB). WebSocket APIs use VPC links V1 and support NLB as the integration target.

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

Best practices

Cross-Account Architecture Using a VPC Endpoint

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.

The following example shows a resource policy that allows access from a specific VPC endpoint in Account B:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "execute-api:Invoke",
      "Resource": "execute-api:/*",
      "Condition": {
        "StringEquals": {
          "aws:SourceVpce": "vpce-xxxxxxxxxxxx"
        }
      }
    }
  ]
}

Best practices

Cross-Account Architecture Using a Private Custom Domain Name

Amazon API Gateway supports custom domain names for private APIs. This feature provides an alternative approach for cross-account access that simplifies URL management and decouples the consumer from the API's internal identifier.

In this pattern, the API provider (Account A) creates a private custom domain name backed by an AWS Certificate Manager (ACM) certificate and maps it to a private REST API. The provider then shares the private custom domain name with the API consumer (Account B) using AWS RAM. The consumer creates a domain name access association between their VPC endpoint and the shared private custom domain name, and configures a Route 53 private hosted zone to resolve the custom domain name to the VPC endpoint.

How it works

Considerations

When to use this pattern

Use the private custom domain name approach instead of the VPC endpoint approach when:

Use the VPC endpoint approach when:

For more information, see Custom domain names for private APIs in API Gateway.

On-premises architecture

If you have users accessing from on-premises locations, you 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 inbound endpoint. 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.

DNS resolution options for on-premises clients

On-premises clients need to resolve the private API hostname to the VPC endpoint's private IP addresses. There are three approaches:

Best practices

Multi-Region Private API Gateway using a Network Load Balancer

You might want to build active-active or active-passive multi-Region API deployments for addressing requirements like failover between Regions, reduce API latency when there are API clients in other Regions and meeting data sovereignty requirements.

Because custom domain names were not originally supported for private APIs, this pattern uses a Network Load Balancer (NLB) in front of the API Gateway with the same TLS certificate configured for the desired custom domain name. Each Region has a VPC endpoint set up for the private API Gateway to be accessed from the VPC. A Route 53 private hosted zone in each VPC has alias records pointing to the NLB with the desired routing policy.

The solution has private APIs configured with private custom domain names associated with a certificate from AWS Certificate Manager. Each Region has a VPC Endpoint setup for the private API Gateway to be accessed from VPC. The following routing policies can help in achieving the multi-Region architecture for API Gateway:

To resolve the private API custom domain name, there is an inbound resolver endpoint setup for both Regions, which provides two or more private IPs in each VPC across multiple availability zones to ensure high availability. This enables the resolution of the custom domain name using the VPC resolver.

The solution above uses a Network Load Balancer (NLB), however, an Application Load Balancer (ALB) can be used instead if required. When using an ALB, target groups need to be created with VPC endpoint IP addresses. The target group health check path should be set to /ping (API Gateway service health check) to return a HTTP 200 success code, otherwise the health check will fail with a 403 response. The Route 53 private hosted zone in each VPC has alias records configured to point to ALB hostname with the desired routing policy. The API Gateway, VPC endpoint and Route 53 inbound resolver setup remains as described for the NLB.

The following diagram shows a sample architecture for on-premises clients to access private API Gateway APIs deployed across two AWS Regions. However, the solution described above can equally apply to clients accessing from another VPC or AWS account with appropriate DNS configurations on client VPC and appropriate resource policy on the private API. The on-premises DNS server is configured to forward the request for the private API domain name to the inbound resolver endpoint private IP addresses in the nearest Region and a fallback IP address pointing to the farther Region.

The solution assumes mechanisms are in place to synchronize state (if any) across Regions for the backend APIs and associated datastores.

Best practices

Multi-Region Private API Gateway using Private Custom Domains

This pattern uses private custom domain names in each Region, each backed by an ACM certificate and mapped to the regional private REST API. Route 53 private hosted zone records with failover or weighted routing policies direct traffic to the appropriate Region's VPC endpoint. This approach eliminates the Network Load Balancer required in Multi-Region Private API Gateway using a Network Load Balancer pattern.

Components per Region

Each Region requires the following resources:

Connectivity for on-premises clients

For on-premises clients accessing the multi-Region private API from a corporate data center, the following additional resources are required:

DNS and failover

A Route 53 private hosted zone associated with the client VPC contains records for the custom domain name. The following routing policies can help achieve the multi-Region architecture:

Best practices

Private integration architecture with Amazon ECS

Amazon Elastic Container Service (Amazon ECS) is a fully managed container orchestration service. You can use Amazon ECS to run your most sensitive and mission critical applications because of its security, reliability, and scalability. For private integration in REST APIs, one design pattern is to use an Application Load Balancer to route traffic to an Amazon ECS cluster in private subnets. If you use Amazon ECS as your backend compute service, the following diagram shows clients in one VPC accessing an Amazon ECS cluster in another VPC through a private API and private integration.

Best practices

Private integration cross-account

Many customers want to use API Gateway with resources that exist in a different AWS account. Although the VPC Link must exist in the same account as the API Gateway API, it is still possible to access resources in another account using AWS PrivateLink or through private VPC routing such as VPC peering or using AWS Transit Gateway.

API Gateway supports VPC links V2 for REST APIs. VPC links V2 allow private integrations with Application Load Balancers (ALB) in addition to Network Load Balancers. VPC links V1 (NLB-only) are considered legacy and AWS recommends using VPC links V2 for new implementations.

The following diagram shows a sample architecture where a PrivateLink (VPC Endpoint Service) connection has been established between the Central API Gateway Account and an Elastic Container Service (ECS) cluster in Resource Account A and a EC2 Auto Scaling Group (ASG) in Resource Account B. As this is a REST API Gateway the VPC Link uses a Network Load Balancer (NLB) to point to the private IP addresses of the VPC Endpoint for each PrivateLink connection. API Gateway can invoke cross-account Lambda functions without the need for VPC link by using resource-based policies.

In the preceding example there is no private routing between the different account VPCs. PrivateLink provides a secure private connection to a single endpoint. Example use cases for this architecture include where there are overlapping CIDR ranges between VPCs, or you wish to provide access to only a specific service or application rather than create a route to all resources in another VPC.

With VPC links V2, you can use either an ALB or an NLB in the Central API Gateway Account as the VPC link target. ALB support for REST APIs via VPC Link V2 was introduced in November 2025. For existing implementations using VPC Link V1 or earlier REST API setups, migration to V2 might be required to leverage ALB integration. The load balancer's target group uses IP-type targets pointing to the private IP addresses of the VPC endpoints (PrivateLink connections to the Resource Accounts).

For this cross-account PrivateLink pattern, consider the following when choosing between ALB and NLB in the Central Account. ALB is appropriate when you need Layer 7 features in the Central Account, such as path-based routing to direct traffic to different Resource Account backends, or host-based routing to consolidate multiple services behind a single VPC link.

In the following architecture there is no private routing between the different account VPCs. PrivateLink provides a secure private connection to a single endpoint. Example use cases for this architecture include where there are overlapping CIDR ranges between VPCs, or you want to provide access to only a specific service or application rather than create a route to all resources in another VPC.

Resource Account Requirements

Each Resource Account must expose its backend behind an NLB configured as a VPC Endpoint Service target. Only Network Load Balancers (NLB) or Gateway Load Balancers (GWLB) can serve as VPC Endpoint Service targets. Application Load Balancers cannot be used directly as VPC Endpoint Service targets. If your backend uses ALBs, place an NLB in front of the ALB within the Resource Account.

The Resource Account NLB serves as the PrivateLink service provider and is separate from the Central Account load balancer used for the VPC link. This architecture requirement applies regardless of whether the Central Account uses VPC Link V1 or V2.

Connection Management

Best Practices

Central Account Configuration

Monitoring and Security

If you already have a cross-account VPC architecture in place using VPC Peering or AWS Transit Gateway. NLB or ALB can be used for the VPC Link and pointed directly to the private IP addresses of the resources in a different account, removing the need for the VPC Endpoint and simplifying the architecture. This is shown in the following sample architecture.

The following summary highlights the main architecture features of the API architectural patterns described above:

PrivateLink Pattern

VPC Peering Pattern

Best Practices