Amazon API Gateway offers REST APIs and HTTP APIs (as well as WebSocket APIs). What would make you choose a REST API over an HTTP API, and what are you giving up if you default to HTTP APIs?

## Three products behind one console "API Gateway" is really three API types with two different control planes. **REST APIs** are the original service (the v1 control plane, `AWS::ApiGateway::RestApi`). **HTTP APIs** and **WebSocket APIs** are both v2 (`AWS::ApiGatewayV2::Api`). They are not versions of each other in the sense of an upgrade path — an HTTP API is a separate resource with a separate API surface, so "migrating" a REST API is really rebuilding it and cutting traffic over. HTTP APIs exist because the overwhelmingly common use of API Gateway is boring: take an HTTPS request, authorize it, hand it to a Lambda function or an HTTP backend, return the response. REST APIs charge for, and impose configuration weight for, a lot of machinery most of those services never touch. ## What you get by choosing an HTTP API - **Lower per-request cost.** At entry volumes an HTTP API request costs roughly a third of a REST API request. On a high-traffic public API this is a real line item, not a rounding error. - **Lower added latency.** AWS positions HTTP APIs as meaningfully lower-overhead per call; the service does less work per request because there is no VTL engine, no caching layer and no usage-plan accounting in the path. - **Simpler configuration.** Built-in CORS configuration, an auto-deploying `$default` stage, a `$default` catch-all route, and greedy route syntax such as `ANY /{proxy+}`. - **Built-in JWT authorizers.** HTTP APIs can validate an OIDC/OAuth 2.0 JWT natively, with no authorizer Lambda at all — something REST APIs cannot do (they need a Lambda authorizer or a Cognito user-pool authorizer). - **Payload format 2.0** for Lambda proxy integrations, which is a flatter, smaller event than the REST-era 1.0 shape. ## What only REST APIs have The list is what trips teams up, because each item is something people assume is "just there": - **API keys and usage plans** — per-consumer quotas and rate limits enforced by the gateway. - **Stage response caching** — a managed cache in front of your integration. - **Request validation** — reject a malformed body against a JSON Schema model before the backend is ever invoked. - **VTL mapping templates** — full request *and* response transformation, and with them the `AWS` integration type: calling another AWS service directly, with no Lambda in between. - **Endpoint types** — REST APIs can be `EDGE`, `REGIONAL` or `PRIVATE`. HTTP APIs are regional only; there is no private HTTP API. - **AWS WAF association**, **X-Ray active tracing**, **canary release deployments**, and **API resource policies**. ## What both types do Lambda proxy (`AWS_PROXY`) and HTTP proxy integrations, private integrations to a VPC backend through a VPC link, custom domain names with base-path/API mappings, stages, throttling, CloudWatch metrics and access logs, IAM (SigV4) authorization, Lambda authorizers, and mutual TLS on a custom domain. So the shared ground is large; the gap is at the edges. ## The limit that applies to both Both types are synchronous request/response front doors and cap how long a single integration may take — on the order of 30 seconds (REST APIs default to 29 s, HTTP APIs to 30 s), with the cap raisable on request for some endpoint types. Anything longer needs a different shape: accept the request, return `202 Accepted` with a job id, and let the client poll — or hand the work to Step Functions or a queue. Candidates who propose "just raise the timeout" for a five-minute report generation are missing this. ## How I actually decide Start from HTTP API. Escalate to REST only on a concrete requirement: - I must sell metered access to third parties → REST (usage plans). - The API must be unreachable from the internet → REST (`PRIVATE` endpoint type). - I need WAF rules on the API itself → REST (or front an HTTP API with CloudFront/ALB, which changes the architecture). - I want to drop events straight into SQS with no compute → REST (`AWS` integration + VTL), though a small Lambda is often simpler to own than a VTL template nobody on the team can read. - I need heavy request/response reshaping to keep a legacy contract → REST. And the third flavor: **WebSocket APIs** are not a competitor to either. Choose one when the client needs server-initiated push over a long-lived connection rather than request/response. ## The trap The expensive version of this mistake is picking HTTP APIs for the price, shipping, and then discovering six months in that the partner integration needs per-key quotas. Because there is no in-place conversion, the fix is a new API plus a cutover. Check the feature list against your roadmap, not just today's requirements.