skip to content

In Amazon API Gateway, what is the difference between a private API and a private integration, and what mechanism implements each one?

level: seniorimportance: should knowfreq 45%

answer

  1. think inbound versus outbound
  2. one restricts callers, one reaches backends
  3. endpoint type versus VPC link
  4. REST private integrations want an NLB
  5. HTTP API links take subnets and security groups

basics

~20 s

They control opposite directions. A private API restricts who may call the API: it is a REST API with the PRIVATE endpoint type, reachable only through an interface VPC endpoint for execute-api. A private integration is how the API reaches a backend inside a VPC, using a VPC link.

solid answer

~50 s

A **private API** is about inbound traffic. You create a REST API with endpoint type `PRIVATE`; it then has no internet-facing hostname and is callable only from clients that route through an interface VPC endpoint for `execute-api`, with an API resource policy controlling which endpoints and principals are allowed. HTTP APIs have no private endpoint type at all. A **private integration** is about outbound traffic: the API — public or private — needs to reach a backend that lives in private subnets with no public address. That is done through a **VPC link**. For REST APIs the VPC link fronts a Network Load Balancer, and the integration is set to `connectionType: VPC_LINK`. For HTTP APIs the VPC link is created with subnets and security groups and can target an ALB, an NLB, or a Cloud Map service. The two are independent: a fully public API can have a fully private backend, which is the most common production shape.

code

bash · 10 lines
bash
# HTTP API VPC link: lives in your subnets, carries a security group
aws apigatewayv2 create-vpc-link \
  --name orders-vpc-link \
  --subnet-ids subnet-0aa11bb22 subnet-0cc33dd44 \
  --security-group-ids sg-0ee55ff66

# REST API VPC link: fronts a Network Load Balancer
aws apigateway create-vpc-link \
  --name orders-rest-link \
  --target-arns arn:aws:elasticloadbalancing:eu-west-1:111122223333:loadbalancer/net/orders-nlb/abc123

go deeper

for a junior

Know that API Gateway lives outside your VPC, so reaching a backend in private subnets needs a VPC link, and that a private API is a separate idea about who may call you.

for a middle

Explain both directions concretely: PRIVATE endpoint type plus an interface VPC endpoint for inbound, VPC link plus NLB (REST) or ALB/NLB/Cloud Map (HTTP API) for outbound.

for a senior

Show the diagnosis instincts — 403 on a private API means resource policy or DNS, integration timeouts mean target health or security groups — and lay out which combination of the two you would choose for a given exposure requirement.

for a principal

Own the exposure standard across the estate: which APIs may ever be internet-facing, how private connectivity is provisioned consistently, and what you accept in operational cost for the extra load balancers and endpoints that a fully private posture requires.

## Two different words that both sound like "private" This is one of the most reliable ways to separate someone who has actually built on API Gateway from someone who has read the marketing page. "Private API" and "private integration" sit on opposite sides of the gateway. ``` client ──(inbound: who may call me?)──▶ API Gateway ──(outbound: how do I reach my backend?)──▶ service private API / endpoint type private integration / VPC link ``` ## Private API — the inbound side A private API is a **REST API** created with the endpoint type `PRIVATE`. Its practical properties: - It has **no publicly routable front door**. Requests must arrive through an **interface VPC endpoint** for the `com.amazonaws.<region>.execute-api` service in a VPC you control (or a VPC connected to it), which puts elastic network interfaces with private addresses into your subnets. - It **requires an API resource policy**. Without one that allows the caller, everything is denied — this is not optional the way it is on a regional API. The usual policy condition restricts by `aws:SourceVpce` (a specific endpoint) or `aws:SourceVpc`. - Callers reach it over the endpoint's private DNS or the endpoint-specific hostname; a plain public DNS lookup of a `PRIVATE` API's hostname gets you nowhere useful from the internet. - The security group **on the interface endpoint** decides which clients inside the VPC may open a connection to it — a step people forget, then blame DNS. HTTP APIs and WebSocket APIs have no equivalent endpoint type. If the requirement is "never reachable from the internet, full stop", that constrains you to a REST API. ## Private integration — the outbound side The far more common need: your API is public (or regional), but the service behind it runs on ECS tasks or EC2 instances in private subnets with no public IPs. API Gateway is an AWS-managed service outside your VPC, so it cannot simply open a socket to `10.0.x.x`. A **VPC link** bridges that gap with AWS-managed network interfaces in your subnets. The two API types implement it differently, and mixing them up is a common wrong answer: - **REST API:** create a VPC link that targets a **Network Load Balancer**. The method's integration is an `HTTP` or `HTTP_PROXY` integration with `connectionType` set to `VPC_LINK` and the link's id supplied. NLB only — an ALB is not a valid REST VPC link target, so teams that already run an ALB usually put an NLB in front of it or switch API type. - **HTTP API:** create a VPC link (the v2 kind) with **subnet ids and security group ids**, then point a private integration at an **ALB listener, an NLB listener, or an AWS Cloud Map service**. This is more flexible and is one of the better reasons to prefer HTTP APIs for containerised backends. Because the link's interfaces live in your subnets, ordinary VPC rules apply: the backend's security group must allow traffic from the link's security group (HTTP API) or from the NLB (REST API), and the subnets must have routes to the targets. ## What a private integration is not - It is **not a NAT gateway**. NAT is for resources *in* your VPC reaching out; it does nothing for an AWS-managed service reaching in. - It is **not an interface VPC endpoint**. Those let clients in your VPC reach an AWS service privately — the inbound half of this picture. - It does **not** make the API private. A public API with a VPC link still accepts requests from anyone on the internet who passes authorization. The only thing that changed is the network path on the far side. ## The combinations you actually see | API reachability | Backend location | What you configure | |---|---|---| | Public/regional | Public HTTP endpoint | Plain HTTP proxy integration | | Public/regional | Private subnets | VPC link (private integration) | | Private (`PRIVATE`) | Private subnets | Interface endpoint + resource policy, **and** a VPC link | | Private (`PRIVATE`) | Public endpoint | Legal but unusual | The third row is where interviewers like to sit, because it forces you to say both halves out loud and to notice that they are configured independently. ## Failure modes worth naming - Calls to a private API return **403** with no useful message: nine times out of ten the resource policy does not allow the caller's `aws:SourceVpce`, or private DNS is disabled on the interface endpoint so the client resolved the public name. - A private integration times out: the target group is unhealthy, or the backend security group does not allow the VPC link's security group. - A team "secures" an API by adding a VPC link and is surprised it is still callable from the internet — the two directions were never connected.

  • Your REST API needs a private integration but the service already sits behind an Application Load Balancer. What now?
    A REST API VPC link can only target a Network Load Balancer, so you either place an NLB in front of the existing ALB (NLB target group pointing at the ALB), or move that API to an HTTP API, whose VPC links accept an ALB listener directly. Which you choose usually depends on whether you need any REST-only features on that API.
  • Calls to a private API fail with 403 even from inside the right VPC. Where do you look first?
    The API resource policy, then DNS. Private APIs deny by default, so the policy must allow the caller — typically conditioned on `aws:SourceVpce` or `aws:SourceVpc`. If the policy is right, check that private DNS is enabled on the interface endpoint and that the endpoint's security group permits HTTPS from the client, otherwise the request never arrives.
  • Does using a VPC link keep traffic off the public internet?
    Yes for the integration hop — the link uses AWS-managed network interfaces inside your subnets, so gateway-to-backend traffic stays on the AWS network. The client-to-gateway hop is unchanged: on a public or regional API it still arrives over the internet unless you also make the API private or front it with something else.

saying these in an interview costs you the question

  • Says a VPC link makes the API itself private
  • Proposes a NAT gateway so API Gateway can reach private subnets
  • Claims HTTP APIs support the PRIVATE endpoint type
  • Forgets that private APIs require a resource policy
  • Points a REST API VPC link at an Application Load Balancer

context

resolving links…