beginnerintermediateadvanced

AWS · Section 18

API Gateway and API Front Doors

Level: intermediate
Read: 25 min
Concepts: 4

API Gateway fronts an API with a genuinely different feature set depending on type: REST APIs carry the full surface (API keys, usage plans, request validation, WAF), while HTTP APIs are a deliberately minimal, cheaper subset. This section covers that choice, the Lambda-integration and private-VPC-backend patterns available through a VPC link, the hard 29-second/10MB REST API ceilings that force async design for longer workloads, and when a plain ALB is the better fit than API Gateway at all.

This section

AWS API Gateway Tutorial - How To Create REST API With API GatewayCloud Guru

What is true here

REST API = full feature set (API keys, usage plans, request validation, WAF) at higher cost; HTTP API = minimal, cheaper subset.
A stage is a deployed config snapshot; REST APIs require an explicit deployment to publish changes, HTTP APIs deploy automatically.
A VPC link routes API Gateway traffic into a private ALB/NLB (or Cloud Map on HTTP APIs) without the backend needing a public IP.
REST API integration timeout maxes at 29 seconds and payload at 10 MB, independent of the backend's own configured limits.
ALB fits better than API Gateway when the workload needs longer synchronous requests or none of API Gateway's API-management features are needed.

What you will be able to do

Choose between a REST API and an HTTP API based on which specific features the use case actually requires
Route API Gateway traffic to a private VPC backend via a VPC link without exposing it publicly
Recognize when a workload needs an async pattern because it would exceed API Gateway's timeout or payload ceilings
Decide when ALB is the more appropriate front door than API Gateway

From an API type choice to whether API Gateway fits at all

REST or HTTP API

Lambda or private backend

Timeout + payload ceilings

Or: ALB instead

API Gateway and API Front Doors

REST vs HTTP APIs, Lambda and private backend integration patterns, hard timeout/payload limits, and when ALB fits better.

REST APIs vs HTTP APIs

coreintermediate

REST APIs carry the full feature set — API keys, per-client throttling via usage plans, request validation, AWS WAF, private endpoints — at a higher price. HTTP APIs are a minimal, cheaper subset built for the common case: JWT authorizers, Lambda/HTTP integrations, and automatic deployments, without API keys or request validation.

Think of it as

A stage is a named, deployed snapshot of an API's configuration (like "prod" or "dev") — a deployment is what publishes the current configuration to a stage. An authorizer sits in front of every request, deciding who gets past the door before the backend integration ever runs.

What we're doing: See why choosing REST vs HTTP API is a feature decision, not just a naming one.

decision.txttext

Need per-client rate limiting with distinct API keys per partner?
→ REST API (usage plans + API keys are REST-API-only features)

Need a simple JWT-authenticated Lambda backend, lowest cost?
→ HTTP API (JWT authorizer built in, automatic deployments, cheaper)

2: Usage plans and API keys are simply not available on HTTP APIs — this alone forces REST API regardless of any other preference.
4: HTTP APIs support JWT authorizers natively and skip REST API's extra features the use case doesn't need, which is exactly what keeps them cheaper.

Why this works: The two API types are not "the same thing at two price points" — HTTP API is a deliberately reduced feature set, so the decision has to start from which specific REST-API-only feature (if any) the use case actually needs.

Choosing HTTP API for cost, then discovering a required feature is missing

Wrong

text

# "HTTP APIs are cheaper, so default to them" — chosen before checking
# whether request validation or per-client API keys are needed

Better

text

# Check the feature list first (usage plans, request validation, WAF,
# private endpoints) — only default to HTTP API once none are required

What you see: Mid-project, a requirement for per-partner API keys or request-body validation surfaces, and the entire API has to be rebuilt as a REST API because HTTP API cannot add those features later.

Why: REST-API-only features are structural, not configuration toggles — an HTTP API has no upgrade path to gain usage plans, request validation, or WAF integration without recreating the API as a REST API.

A request through API Gateway

Client request

Authorizer

Lambda, JWT, or IAM

Stage

deployed config snapshot

Integration

Lambda, HTTP, AWS service

Remember: REST API = full feature set (API keys, usage plans, request validation, WAF) at higher cost. HTTP API = minimal, cheaper subset (JWT authorizer, automatic deployments). Stage = deployed config snapshot; a deployment is what publishes to it.

API Gateway + Lambda vs Private Backend Patterns

coreintermediate

API Gateway + Lambda is the classic serverless API: each route triggers a function, no server ever runs when idle. API Gateway + private backend routes to resources inside a VPC (an ALB, an NLB, or Cloud Map service discovery) via a VPC link, letting a public API front a backend that never gets a public IP.

Think of it as

API Gateway + Lambda is a receptionist who personally does the work themselves when asked. API Gateway + a private backend is a receptionist who instead walks the request down a private hallway (the VPC link) to a department that has no public entrance at all.

text

API Gateway → Lambda integration          (serverless)
API Gateway → VPC link → private ALB/NLB  (private backend)

What we're doing: See a VPC link route requests to a private backend without exposing it publicly.

private-integration.shbash

aws apigatewayv2 create-vpc-link --name backend-link --subnet-ids subnet-1a subnet-1b
aws apigatewayv2 create-integration --api-id abc123 --integration-type HTTP_PROXY \
  --connection-type VPC_LINK --connection-id vpclink-xyz --integration-uri arn:aws:elasticloadbalancing:...

1: The VPC link is created against private subnets — it establishes the network path without giving the backend a public IP.
3: The integration references the VPC link's connection-id rather than a public URL, so traffic never leaves the VPC boundary to reach the backend.

Why this works: A VPC link is what lets a public-facing API front a backend that intentionally has no public exposure at all — the backend's security posture does not have to change just to be reachable through an API.

Giving a backend a public IP just to make it reachable from API Gateway

Wrong

text

# Attach a public IP / internet-facing ALB to the backend "so API Gateway can reach it"

Better

text

# Use a VPC link — API Gateway can reach a fully private ALB/NLB without
# either side needing any public exposure

What you see: A backend that should only ever be reached through the API is now also directly reachable from the public internet, widening the attack surface unnecessarily.

Why: A VPC link exists precisely to remove this trade-off — it lets API Gateway route into a VPC over a private connection, so the backend never needs a public IP or internet-facing load balancer just to satisfy the API layer.

Two ways API Gateway reaches a backend

Lambda integration

+The receptionist does the work personally
+No server runs when idle
+Classic serverless pattern

VPC link → private ALB/NLB

−Routed down a private hallway, not the public internet
−Backend never needs a public IP
−Fronts an existing containerized/EC2 service

Choosing the integration pattern

Choosing the integration pattern
Backend	Pattern
Serverless function per route	API Gateway + Lambda integration
Existing containerized/EC2 service inside a VPC	API Gateway + VPC link → private ALB/NLB
API itself must never be reachable from the public internet	Private REST API (endpoint type PRIVATE)
Service discovered dynamically inside a VPC	HTTP API + Cloud Map private integration

Together

bash

aws apigatewayv2 create-vpc-link --name my-link --subnet-ids subnet-1 subnet-2

Remember: API Gateway + Lambda: classic serverless, no idle server. API Gateway + VPC link: routes to a private ALB/NLB (or Cloud Map on HTTP APIs) with no public IP needed on the backend.

Timeout, Payload, and Rate Limits

standardintermediate

API Gateway REST APIs cap integration timeout at 29 seconds and payload size at 10 MB, regardless of what the backend itself is configured for. A workload that needs longer or larger has to be redesigned around an async pattern, not given a longer wait.

Think of it as

API Gateway's integration timeout is a hard ceiling independent of the backend's own timeout — even a Lambda function configured for 15 minutes gets cut off by API Gateway's own limit if fronted by a REST or HTTP API.

text

REST API integration timeout: max 29s (hard limit, not adjustable)
REST API payload: max 10 MB

What we're doing: See why a long-running Lambda function still needs an async pattern behind API Gateway.

timeout-mismatch.txttext

Lambda function timeout: 900 seconds (15 minutes)
API Gateway integration timeout: 29 seconds (fixed ceiling)
→ Any synchronous request over 29s is cut off by API Gateway first

1: Lambda itself is happy to run for up to 15 minutes if invoked directly or asynchronously.
2: API Gateway's own integration timeout applies on top of that and is not configurable past 29 seconds for REST APIs, so it becomes the effective ceiling for any synchronous call through the API.

Why this works: The two timeouts are independent limits stacked on the same request — the shorter one always wins, which is why a synchronous long-running workload through API Gateway needs to be redesigned as async rather than just given a longer Lambda timeout.

Remember: REST API integration timeout maxes out at 29 seconds and REST API payloads at 10 MB — both hard ceilings independent of the backend's own limits. Workloads that exceed either need an async pattern, not a longer wait.

When ALB Fits Better Than API Gateway

standardintermediate

ALB fits better than API Gateway when a workload needs longer synchronous requests than API Gateway allows, or when none of API Gateway's API-management features (keys, usage plans, request validation) are actually needed — ALB just routes and load-balances HTTP traffic, with no per-request API-management overhead.

Think of it as

API Gateway is built for API-shaped concerns — request validation, usage plans, per-client throttling, Lambda-native integration. ALB is built purely to route and load-balance HTTP traffic to running compute — no API management features, but no 29-second timeout ceiling and no per-request cost either.

text

Need API-management features (keys, usage plans, validation) or Lambda-native routes → API Gateway
Just need to route/balance HTTP traffic to a running service, no per-request billing → ALB

What we're doing: Choose between ALB and API Gateway for a service with long-running requests and no need for API keys.

decision.txttext

Backend: existing ECS service, some requests run 60+ seconds,
no API keys or per-client throttling required.
→ ALB: no 29-second integration ceiling, no API-management overhead to pay for.

1: A request duration past API Gateway's fixed REST API integration ceiling directly rules out a synchronous API Gateway route for this endpoint.
2: With no API-management requirement, none of API Gateway's differentiating features are actually being used, which removes the reason to pay for and operate it.

Why this works: API Gateway earns its cost and complexity through API-management features — when none of those features are needed and the backend already runs continuously, ALB is simply a more direct fit for pure HTTP routing and load balancing.

Remember: Choose ALB over API Gateway when the workload needs longer synchronous requests than API Gateway's ceiling allows, or when none of API Gateway's API-management features (keys, usage plans, validation) are actually needed.