Amazon API Gateway: What It Is and When to Use It

Definition

Amazon API Gateway is a fully managed service for creating, publishing, securing, and operating APIs at any scale. You define the API's routes and methods, plug in backend integrations (Lambda, HTTP endpoints, AWS services, EC2, ECS via VPC Link), layer on authentication and throttling, and API Gateway handles TLS termination, request routing, auth, throttling, monitoring, and caching for you. It is the default way to put a scalable HTTPS front door on Lambda-based or container-based services.

API Types

API Gateway offers three API types, each tuned to a different workload:

1. REST API

• Feature-rich: request/response mapping templates, response transformations, API keys, usage plans, Lambda authorizers, WAF, per-resource caching, private APIs (inside a VPC), SDK generation, mutual TLS.
• Higher latency and cost than HTTP API — but more knobs.
• Best for enterprise APIs needing API keys, usage plans, or rich request/response transformation.

2. HTTP API

• Simpler, cheaper, faster — ~70% cheaper than REST API, ~50% lower latency.
• Core features: JWT authorizer (OIDC / Cognito), Lambda authorizer, CORS, custom domains, stage variables.
• Missing vs REST API: API keys, usage plans, request/response transformations, private APIs, caching, WAF on some edge cases.
• Best for new Lambda- or container-backed APIs without complex transformations.

3. WebSocket API

• Long-lived bi-directional connections for chat, notifications, collaborative apps.
• Routes based on a $connect / $disconnect / $default + custom route keys in the message body.
• Integrates with Lambda or HTTP backends.
• Best for stateful real-time applications.

Key Features

• Integrations: Lambda (the most common), HTTP backend, any AWS service via SigV4, VPC Link (to private ALB / NLB), mock (fixed responses for testing).
• Authentication & authorization: IAM (SigV4), Cognito User Pools, Lambda authorizers (custom token/request), JWT authorizers (HTTP API), API keys (REST API only).
• Request validation: JSON Schema on the body, required query params/headers.
• Throttling and usage plans: default 10,000 RPS account limit, per-API and per-key throttling, burst/rate limits.
• Caching (REST API only): per-stage response cache, 0.5 GB to 237 GB, reduces backend hits and cost.
• Stages and deployments: /dev, /staging, /prod; deployments are versioned and rollback-capable.
• Custom domains: with ACM TLS certificates and Route 53 alias records.
• Private APIs (REST only): accessible only through VPC Interface Endpoints.
• Mutual TLS (REST API): client certificate auth for B2B integrations.
• WAF integration: protect REST APIs against SQL injection, XSS, etc.
• CloudWatch Logs & metrics: per-method latency, 4xx/5xx, cache hit ratio.
• X-Ray tracing: end-to-end distributed tracing through to Lambda and downstream services.
• Lambda Proxy integration: a simple pattern where the entire request is forwarded to Lambda as an event object, and Lambda's return value becomes the HTTP response.

Common Use Cases

1. Serverless REST / HTTP APIs — Lambda behind API Gateway is the canonical serverless backend pattern.
2. Public SaaS APIs with key-based billing — REST API with API keys + usage plans for metering.
3. Mobile and web backends — HTTP API with Cognito JWT authorization.
4. Real-time applications — WebSocket API for chat, notifications, collaborative editing.
5. API facade in front of ECS / EKS — HTTP API with VPC Link to a private ALB fronting containers.
6. B2B APIs with mutual TLS — REST API with client-certificate auth.
7. Webhook receivers — simple endpoint that triggers Lambda on incoming events.

Pricing Model

• REST API: per million API calls (tiered). Caching adds per-hour charge by cache size.
• HTTP API: per million API calls, ~70% cheaper than REST.
• WebSocket API: per million messages + per million connection-minutes.
• Data transfer out: standard AWS rates.
• No charge for API Gateway when no calls occur — true pay-per-use.

Free Tier includes 1 million REST/HTTP API calls and 1 million WebSocket messages per month for the first 12 months.

Pros and Cons

Pros

• Managed TLS, authentication, throttling, caching, logging — no custom code.
• Deep Lambda integration, including low-latency HTTP APIs.
• Pay-per-use pricing, truly scale-to-zero.
• WebSocket support for real-time.
• Stage versioning supports canary and blue/green rollouts.

Cons

• REST API has higher base latency (tens of ms) vs direct ALB.
• Some limits (payload size 10 MB, integration timeout 29 seconds for REST/HTTP) are inflexible.
• Request/response mapping templates (Velocity) are powerful but fiddly.
• HTTP API is missing several REST API features — migrating between them isn't always trivial.
• WebSocket pricing can be expensive for always-on long-lived connections.

Comparison with Alternatives

| | API Gateway (REST/HTTP) | Application Load Balancer | Lambda Function URLs | AWS AppSync | | --- | --- | --- | --- | --- | | Protocol | HTTPS (and WebSocket) | HTTPS, gRPC, WebSocket | HTTPS | GraphQL | | Targets | Lambda, HTTP, AWS services, VPC | EC2, ECS, Lambda, IP | Single Lambda | Lambda, DynamoDB, HTTP resolvers | | Auth options | IAM, Cognito, JWT, Lambda authorizer, API keys | Cognito, OIDC | IAM or none | Cognito, IAM, OIDC, Lambda | | Features | Throttling, caching, transformations | Path/header routing, sticky sessions | None | Subscriptions, merged schemas | | Best for | Managed APIs with auth/throttling | Load balancing containers / EC2 | Simplest Lambda endpoint | GraphQL APIs |

Exam Relevance

• Solutions Architect Associate (SAA-C03) — API Gateway + Lambda as the standard serverless API pattern, authorizers, CloudFront in front for caching, private APIs via VPC endpoints.
• Developer Associate (DVA-C02) — heavy coverage: REST vs HTTP API differences, Lambda proxy integration, stages and deployments, usage plans and API keys, Lambda authorizers.
• Security Specialty (SCS-C02) — WAF integration, mutual TLS, private APIs, resource policies for cross-account access.

Classic exam trap: HTTP API is not the same as REST API. Scenarios that mention API keys, usage plans, caching, private APIs, or request/response transformation point to REST API.

Frequently Asked Questions

Q: Should I use API Gateway REST API or HTTP API?

A: HTTP API is the default for new, simple, Lambda- or container-backed APIs — ~70% cheaper, ~50% lower latency, and has the core features most teams need (Cognito/JWT auth, CORS, custom domains). REST API remains the right choice when you need API keys and usage plans (for B2B metering), per-stage caching, WAF on private APIs, request/response transformation, or mutual TLS. If your API is publicly-authenticated Lambda, start with HTTP API.

Q: What's the difference between Lambda Proxy integration and Lambda custom integration?

A: Proxy integration forwards the raw HTTP request to the Lambda as an event object; the Lambda returns a structured response ({statusCode, headers, body}) that becomes the HTTP response. Almost all new APIs use proxy integration because it's simple and keeps logic in code. Custom integration uses Velocity mapping templates in API Gateway to transform the request into a specific format before Lambda sees it, and transform the Lambda's output on the way back. Use custom integration when you need to make Lambda speak a fixed contract (e.g., for SDK-generated clients).

Q: How do I put authentication on an API Gateway endpoint?

A: Several options: Cognito User Pools (most common for mobile/web apps — API Gateway validates the JWT against the Cognito pool), JWT authorizer (HTTP API — validates any OIDC JWT), Lambda authorizer (custom code validates tokens or requests), IAM authorization (SigV4-signed requests, typically for internal service-to-service), API keys + usage plans (REST API — for metering B2B API consumers). Choose based on the consumer type and the auth system already in place.

---

This article reflects AWS features and pricing as of 2026. AWS services evolve rapidly — always verify against the official Amazon API Gateway documentation before making production decisions.