AWS API Gateway: Managed REST, HTTP & WebSocket APIs

Q: HTTP API or REST API — which should I use?

HTTP API for most cases — it's cheaper, faster, and simpler, covering the common needs (routing, JWT/Cognito auth, throttling, Lambda/HTTP integration). Choose REST API only when you need a feature it exclusively provides: fine-grained request validation/transformation, response caching, API-key usage plans, or direct WAF integration. Start with HTTP APIs and upgrade only for a concrete reason.

Q: How do I secure an API Gateway endpoint?

Use an authorizer: a Cognito authorizer (validates user-pool JWTs), a JWT authorizer (any OIDC provider), IAM authorization (AWS-to-AWS), or a custom Lambda authorizer (your own logic). The authorizer validates each request at the gateway before it reaches your backend, so unauthorized requests are rejected at the edge. Add throttling and, for public APIs, usage plans with API keys. See API security.

Q: Can API Gateway do real-time / WebSockets?

Yes — WebSocket APIs support persistent bidirectional connections for real-time features (chat, live dashboards, notifications), managing connections and routing messages to Lambda or other backends. It's AWS's managed way to run WebSocket APIs without operating the connection infrastructure yourself.

AWS API Gateway

Amazon API Gateway is AWS's managed service for creating, publishing, securing, and scaling APIs — the front door that sits between clients and your backend (Lambda functions, EC2/containers, or any HTTP service). It handles the cross-cutting concerns of running an API — authentication, rate limiting, request validation, throttling, caching, and TLS — so your backend doesn't reimplement them. It's the AWS-native implementation of the API gateway pattern.

API Gateway is most associated with serverless APIs: paired with Lambda, it's the standard way to build an API where AWS runs everything — no servers to manage, automatic scaling, pay-per-request. But it fronts any backend, and its authorizers (including Cognito and custom Lambda auth) and throttling make it a real security and traffic-management layer. Everything on the general API gateway page applies; this is the AWS service.

TL;DR

API Gateway is AWS's managed API gateway — routing, auth, throttling, caching, and TLS in front of your backend, fully managed and auto-scaling.
Three API types: HTTP APIs (cheaper, faster, simpler — the default for most REST-style APIs), REST APIs (older, more features — request validation, caching, API keys), and WebSocket APIs (real-time bidirectional).
The signature pattern: API Gateway + Lambda = fully serverless API (no servers, scales automatically, pay per request).
Authorizers secure endpoints: Cognito (validate user-pool JWTs), IAM, or custom Lambda authorizers (your own logic / JWT validation).
Built-in throttling (rate limiting), usage plans + API keys (per-consumer quotas), caching, request/response transformation, and stages (dev/prod deployments).
Choose HTTP APIs unless you need a REST-API-only feature; it's cheaper and simpler for the common case.

Core Concepts

API Types: HTTP vs REST vs WebSocket

AWS confusingly offers multiple API Gateway flavors:

The guidance: start with HTTP APIs — they cover most needs at lower cost and latency. Reach for REST APIs only when you need a feature they exclusively offer (fine-grained request validation/transformation, built-in caching, API-key usage plans, direct WAF integration). WebSocket APIs are for genuinely real-time use cases.

The Serverless API Pattern

API Gateway's most common use is fronting Lambda for a fully serverless API:

AWS runs everything — no servers, automatic scaling from zero to high traffic, pay only per request/execution. This is the backbone of countless serverless backends (often defined with SAM or the CDK, or frameworks like the Serverless Framework). API Gateway can also proxy to containers/EC2 or any HTTP endpoint, and route to AWS services directly.

Security: Authorizers

API Gateway secures endpoints with authorizers that validate each request before it reaches your backend:

Cognito authorizer — validates JWT tokens from a Cognito user pool automatically (the managed-auth path).
IAM authorization — for internal/AWS-to-AWS access using SigV4 signatures.
Lambda authorizer (custom) — your own Lambda function runs auth logic (validate a third-party JWT, call an OAuth provider, check custom rules) and returns allow/deny.
JWT authorizer (HTTP APIs) — validate tokens from any OIDC provider directly.

This offloads authentication from your backend to the gateway — the API security principle of validating identity at the edge.

Traffic Management and Operations

Throttling — built-in rate limiting (account and per-method limits) protects backends from spikes and abuse.
Usage plans + API keys — per-consumer quotas and rate limits (for public/partner APIs) — the API-monetization/quota feature (REST APIs).
Caching — cache responses at the gateway (REST APIs) to reduce backend load and latency.
Request/response transformation — reshape payloads between client and backend (REST APIs).
Stages — deploy to named stages (dev, prod) with stage variables, enabling promotion and versioning (see API versioning).
Monitoring — integrates with CloudWatch for metrics and logs.

Common Mistakes

Defaulting to REST APIs When HTTP APIs Suffice

REST APIs are older, more expensive, and higher-latency than HTTP APIs. Teams pick them out of habit and overpay. Use HTTP APIs by default; only choose REST APIs when you specifically need a REST-only feature (request validation/transformation, response caching, API-key usage plans, direct WAF). Check the feature comparison before defaulting to REST.

No Throttling / Usage Plans

Leaving an API without throttling means a traffic spike or abusive client can overwhelm (and run up costs on) your backend. Configure throttling limits, and for public/partner APIs use usage plans with API keys to enforce per-consumer quotas. Rate limiting at the gateway is defense the backend gets for free.

Skipping the Authorizer (or Auth in Lambda)

Validating auth inside each Lambda instead of at the gateway means every function reimplements it (and unauthenticated requests still invoke — and bill — your Lambda). Use an authorizer so unauthorized requests are rejected at the edge before reaching your backend — cheaper and more secure. See API security.

Cold Starts and Timeouts (Lambda Integration)

API-Gateway-fronted Lambda inherits Lambda's cold starts (first-request latency after idle) and API Gateway's request timeout (29 seconds for REST/HTTP APIs). Long-running requests will time out — use async patterns (SQS/Step Functions) for slow work, and mitigate cold starts (provisioned concurrency) for latency-sensitive endpoints.

Ignoring Payload and Cost Limits

API Gateway has payload size limits and per-request pricing; high-volume APIs can get expensive (especially REST APIs). Model the cost, use HTTP APIs, cache where possible, and for very high throughput consider whether a load balancer-fronted service is more economical. See cloud costs.

FAQ

HTTP API or REST API — which should I use?

HTTP API for most cases — it's cheaper, faster, and simpler, covering the common needs (routing, JWT/Cognito auth, throttling, Lambda/HTTP integration). Choose REST API only when you need a feature it exclusively provides: fine-grained request validation/transformation, response caching, API-key usage plans, or direct WAF integration. Start with HTTP APIs and upgrade only for a concrete reason.

What's the API Gateway + Lambda pattern?

The standard serverless API: API Gateway receives requests (handling routing, auth, throttling) and invokes a Lambda function per request to run your code. AWS manages everything — no servers, automatic scaling, pay per request/execution. It's the backbone of serverless backends and the most common way API Gateway is used, though it can front any backend.

How do I secure an API Gateway endpoint?

Use an authorizer: a Cognito authorizer (validates user-pool JWTs), a JWT authorizer (any OIDC provider), IAM authorization (AWS-to-AWS), or a custom Lambda authorizer (your own logic). The authorizer validates each request at the gateway before it reaches your backend, so unauthorized requests are rejected at the edge. Add throttling and, for public APIs, usage plans with API keys. See API security.

How does this relate to the general API gateway concept?

API Gateway is AWS's managed implementation of the API gateway pattern — one entry point handling cross-cutting concerns (auth, throttling, routing, caching) for your APIs. The concept page covers the pattern and alternatives (Kong, Nginx, etc.); this is the AWS-native, serverless-friendly version with deep AWS integration.

Can API Gateway do real-time / WebSockets?

Yes — WebSocket APIs support persistent bidirectional connections for real-time features (chat, live dashboards, notifications), managing connections and routing messages to Lambda or other backends. It's AWS's managed way to run WebSocket APIs without operating the connection infrastructure yourself.