Amazon API Gateway sits in front of your backend (usually Lambda, sometimes HTTP services or other AWS services) and handles routing, authentication, throttling and deployment stages. It offers three API types, and picking the wrong one can mean missing features or paying several times more than needed.
The three types
| REST API | HTTP API | WebSocket API | |
|---|---|---|---|
| Best for | Feature-rich public or enterprise APIs | Simple, fast, low-cost APIs | Real-time two-way messaging |
| Price | Higher per million requests | Significantly lower | Per message and connection minute |
| Auth | IAM, Cognito, Lambda authorizers, API keys | IAM, JWT (Cognito/OIDC), Lambda authorizers | IAM, Lambda authorizer on connect |
| Usage plans and API keys | Yes | No | No |
| Response caching | Yes | No | No |
| Request validation and mapping templates | Yes | Parameter mapping only | Route selection expressions |
| AWS WAF | Yes | No (put CloudFront with WAF in front) | No |
| Private APIs (VPC only) | Yes | No (private integrations to VPC backends only) | No |
REST APIs: the full feature set
REST APIs are the original API Gateway product and still the most capable. Choose them when you need:
- Usage plans and API keys to throttle and set quotas per customer, for example a free tier and a paid tier.
- Request validation against a JSON schema before invoking the backend, saving Lambda invocations on bad input.
- Mapping templates (VTL) to transform requests and call AWS services directly, such as writing to SQS or DynamoDB without a Lambda function.
- Response caching per stage.
- Private APIs reachable only through an interface VPC endpoint.
- AWS WAF on the API stage.
HTTP APIs: simpler and cheaper
HTTP APIs were built for the common case: route requests to Lambda or an HTTP backend with JWT authentication. They have lower latency and a much lower price. Their native JWT authorizer validates tokens from Cognito or any OIDC provider without custom code, and CORS configuration is built in. If you do not need usage plans, caching, validation or WAF at the API layer, start with an HTTP API.
WebSocket APIs: real-time apps
WebSocket APIs keep a persistent connection between clients and API Gateway. Routes like $connect, $disconnect and custom actions (sendMessage) invoke your backend, which can push messages back to any connected client by its connection ID through the management API. Typical uses: chat, live dashboards, multiplayer games, collaborative editing.
Concepts shared by all types
- Stages (dev, prod) with their own settings and stage variables; REST APIs need an explicit deployment to publish changes.
- Throttling: account-level default limits per Region plus per-stage and per-route limits. Clients over the limit receive 429.
- Timeouts: integrations have a maximum timeout (29 seconds by default for REST and HTTP APIs). Long work should run asynchronously.
- Custom domains with ACM certificates and base path mappings.
- Logging to CloudWatch (access logs and execution logs) and tracing with X-Ray.
Common errors and what they mean
| Status | Usual cause |
|---|---|
| 403 Missing Authentication Token | Route or method does not exist, or the stage is not deployed |
| 401/403 | Authorizer rejected the token or IAM signature |
| 429 | Throttled by stage, route or usage plan limits |
| 502 Bad Gateway | Lambda returned a response in the wrong format or crashed |
| 504 | Integration timed out |
How to choose
- Need real-time push? WebSocket API.
- Need usage plans, caching, request validation, WAF on the API, or a private API? REST API.
- Otherwise? HTTP API.
Practice it
Build both styles in Cloud Arena: Serverless CRUD API with a REST API, API Gateway Stages, Mock Integrations and Stage Variables, API Keys and Usage Plans and Cognito User Pool and API Gateway Authorizer. Then debug Orders API Returns 500.
FAQ
Can I migrate from REST to HTTP API?
Yes, if you do not rely on REST-only features. Recreate routes and integrations in an HTTP API and switch the custom domain mapping.
Do I need API Gateway for Lambda?
Not always. Lambda function URLs give a function an HTTPS endpoint directly, and ALBs can invoke Lambda. API Gateway adds auth, throttling, stages and more.