Why architecture matters here
API Gateway matters because it provides the managed API front door -- the cross-cutting concerns (auth, throttling, routing, transformation) -- without you running servers, and it's core to serverless architectures. Every API needs a front door handling the cross-cutting concerns (authentication/authorization, rate limiting, routing, request/response shaping) -- which is significant, undifferentiated work to build and operate (servers, load balancers, the cross-cutting logic, scaling, availability). API Gateway provides this as a managed service (no servers to run -- it handles the front-door concerns, scaling and availability managed by AWS) -- so you focus on your backend logic (the Lambda functions or services) while API Gateway handles the front door. And it's core to serverless (the front door for Lambda-backed APIs -- API Gateway receiving requests and invoking Lambda -- the standard serverless API pattern). For building APIs on AWS (especially serverless), API Gateway is the standard managed front door, and understanding it (its role, features, tradeoffs) is understanding how to build managed APIs on AWS.
The managed-cross-cutting-concerns insight is the core value, and it's what API Gateway provides. An API front door handles cross-cutting concerns -- the things every API needs, orthogonal to the business logic. Authorization: authenticating and authorizing requests (IAM for AWS-signed requests, Cognito for user pools, or custom Lambda authorizers for custom logic) -- so the backend doesn't handle auth (API Gateway does, before routing). Throttling and quotas: rate-limiting requests (protecting the backend from overload) and usage plans/quotas (managing API consumers -- e.g., different limits per API key) -- so the backend is protected and consumers are managed. Request/response mapping: transforming payloads (between the client's format and the backend's -- e.g., mapping a REST request to a Lambda event, or reshaping a response) -- so the client and backend formats can differ. Caching: caching responses (reducing backend load and latency for cacheable responses). By providing these cross-cutting concerns as managed features (configured, not coded/operated), API Gateway lets you handle them declaratively (configuring auth, throttling, mapping, caching) rather than building them -- the core value (managed cross-cutting API concerns). Understanding that API Gateway provides the cross-cutting concerns (auth, throttling, mapping, caching) as managed features is understanding its core value.
And the REST-vs-HTTP-API choice is a key decision, trading features against cost and latency. API Gateway offers two main API types with different tradeoffs. REST APIs: the full-featured option -- with request validation, mapping templates (powerful payload transformation), API keys and usage plans, response caching, and more -- but higher cost (priced more per request) and higher latency (more processing). HTTP APIs: the newer, leaner option -- lower cost (cheaper per request) and lower latency (less processing), but fewer features (no mapping templates, request validation, or built-in caching -- the essentials: routing, JWT/Lambda auth, basic CORS). So the choice trades features (REST -- more) against cost/latency (HTTP -- cheaper, faster): use HTTP APIs when you don't need the REST features (most simple Lambda-backed APIs -- cheaper and faster), and REST APIs when you need the advanced features (request validation, mapping templates, API-key usage plans, caching). This choice (REST for features, HTTP for cost/latency) is a key decision (affecting cost, latency, and available features) -- and defaulting to HTTP APIs (unless you need REST features) is often the cost/latency-optimal choice. Understanding the REST-vs-HTTP tradeoff (features vs cost/latency) is understanding a key API Gateway decision.
The architecture: every piece explained
Top row: the role and types. The role: the managed API front door (receiving requests, applying cross-cutting concerns, routing to backends -- without servers). REST vs HTTP APIs: REST APIs (full-featured -- validation, mapping templates, API keys, caching -- but higher cost/latency) vs HTTP APIs (leaner -- lower cost/latency, fewer features) -- the key type choice. Integrations: the backends -- Lambda (serverless functions -- the common serverless pattern), HTTP endpoints (proxying to HTTP backends), and AWS services (direct integration -- e.g., to SQS, Step Functions) -- what the gateway routes to. Authorization: authenticating/authorizing requests -- IAM (AWS-signed), Cognito (user pools), or Lambda authorizers (custom logic) -- before routing.
Middle row: the cross-cutting features. Throttling and quotas: rate limits (protecting backends from overload) and usage plans/quotas (per-consumer limits -- e.g., per API key) -- protecting backends and managing consumers. Request/response mapping: transforming payloads (mapping templates -- reshaping between the client and backend formats -- REST APIs) -- so formats can differ. Caching: caching responses (reducing backend load and latency for cacheable responses -- REST APIs). Stages and deployments: managing versions and rollouts -- stages (dev/prod -- separate environments) and canary deployments (gradual rollout of a new version -- shifting traffic gradually) -- deployment management.
Bottom rows: real-time and comparison. WebSocket APIs: bidirectional real-time APIs (beyond request/response -- persistent connections for real-time push -- e.g., chat, live updates) -- a distinct API type for real-time. vs ALB / AppSync: API Gateway (managed API front door -- cross-cutting concerns, serverless-friendly) vs ALB (Application Load Balancer -- load-balancing to containers/instances -- for non-serverless, higher-throughput/lower-cost-at-scale) vs AppSync (managed GraphQL -- for GraphQL APIs) -- chosen by the need (API Gateway for managed REST/HTTP APIs, ALB for load-balancing to compute, AppSync for GraphQL). The ops strip: throttling (configuring throttling -- protecting backends from overload, managing consumer quotas -- a key protection), monitoring (monitoring the API -- traffic, latency, errors, throttling -- via CloudWatch -- for reliability and troubleshooting), and cost (API Gateway pricing per request -- so cost scales with traffic; HTTP APIs cheaper than REST -- managing the cost, especially at high request volumes).
End-to-end flow
Trace a request through API Gateway. A client calls a serverless API (backed by Lambda). The request hits API Gateway (the front door). API Gateway applies the cross-cutting concerns: authorization (a Lambda authorizer validates the request's token -- authorizing it, or rejecting if invalid), throttling (checking the rate limit -- rejecting if the client exceeds its quota -- protecting the backend), and (for a REST API) request mapping (transforming the request into the Lambda event format). If the response is cacheable and cached, API Gateway returns the cached response (reducing backend load). Otherwise, it routes to the integration (invoking the Lambda function with the mapped event). The Lambda processes the request and returns a result. API Gateway applies response mapping (transforming the Lambda result into the client response format) and returns it (caching it if configured). So API Gateway handled all the cross-cutting concerns (auth, throttling, mapping, caching) and routed to the Lambda -- the backend just processed the business logic (the Lambda), with API Gateway managing the front door. The managed front door (cross-cutting concerns, routing to Lambda) handled the request without the team running any front-door servers.
The REST-vs-HTTP and authorization vignettes show the choices. A REST-vs-HTTP case: for a simple Lambda-backed API (just routing and JWT auth -- no need for mapping templates, request validation, or caching), the team uses an HTTP API (cheaper per request, lower latency -- the leaner option, sufficient for the simple needs) -- saving cost and latency. For a more complex API (needing request validation, mapping templates to reshape payloads, API-key usage plans, and response caching), they use a REST API (the full-featured option -- worth the higher cost/latency for the features). The choice matched the API type to the needs (HTTP for simple/cost-sensitive, REST for feature-rich). An authorization case: the API needs custom authorization (validating a custom token and checking permissions) -- so the team uses a Lambda authorizer (custom auth logic in a Lambda -- API Gateway invoking it to authorize each request) -- flexible custom authorization (versus IAM or Cognito, which fit AWS-signed or user-pool auth respectively) -- the authorization option matched to the need.
The throttling and comparison vignettes complete it. A throttling case: the API's backend (Lambda, or a downstream service) has capacity limits -- so the team configures throttling (rate limits protecting the backend from overload -- and per-consumer usage plans/quotas -- e.g., different limits per API key for different customers) -- protecting the backend (an overload -- e.g., a traffic spike or an abusive consumer -- throttled at the gateway, not overwhelming the backend) and managing consumers (per-key quotas). A comparison case: the team uses API Gateway for their managed REST/HTTP APIs (the cross-cutting concerns, serverless-friendly); for load-balancing to a container service (high-throughput, non-serverless), they'd use an ALB (cheaper at high throughput, load-balancing to the containers); for a GraphQL API, AppSync (managed GraphQL) -- matching the front-door service to the need. The consolidated discipline the team documents: use API Gateway as the managed API front door (cross-cutting concerns -- auth, throttling, mapping, caching -- without running servers; core to serverless), choose the API type by need (HTTP APIs for simple/cost-sensitive -- cheaper, faster; REST APIs for feature-rich -- validation, mapping, caching), use the right authorization (IAM, Cognito, or Lambda authorizers), configure throttling and quotas (protecting backends, managing consumers), use stages and canary deployments (version/rollout management), consider WebSocket APIs for real-time, monitor the API (traffic, latency, errors), manage the cost (per-request pricing -- HTTP cheaper than REST), and choose API Gateway vs ALB/AppSync by need -- because API Gateway provides the managed API front door (the cross-cutting concerns without servers), core to serverless architectures, with the REST-vs-HTTP choice trading features against cost/latency.