Skipping “what is an API gateway” — this is the model experienced engineers reach for when reasoning about API Gateway in production.

REST, HTTP, and WebSocket APIs are architecturally different products, not feature tiers

It’s tempting to think of HTTP APIs as “REST APIs with fewer features,” but they’re built on different underlying infrastructure with genuinely different capabilities and pricing models. REST APIs support request/response mapping templates written in Velocity Template Language (VTL), usage plans with API keys, and AWS WAF integration; HTTP APIs are a newer, lower-latency, lower-cost product with a leaner feature set (JWT authorizers built in, but no native VTL mapping templates until relatively recently, and different throttling defaults); WebSocket APIs are a distinct routing model entirely, built around persistent connections and route selection expressions rather than HTTP verbs and paths. Choosing between them isn’t a checkbox — it constrains which integration patterns, auth mechanisms, and observability tools are even available to you.

Throttling is a token-bucket algorithm, not a hard request cap

API Gateway’s throttling operates on a token-bucket model with two configurable numbers: a steady-state rate (tokens replenished per second) and a burst capacity (the bucket’s maximum size). This means a client can legitimately send a short burst well above the steady-state rate — up to the burst capacity — without being throttled, as long as the bucket has accumulated enough tokens from prior idle time. Engineers who set only a rate limit without understanding burst capacity often see confusing behavior: identical average request rates from two clients produce different throttling outcomes depending on how bursty each client’s actual traffic pattern is.

Integration type determines how much request/response transformation happens in the gateway itself

API Gateway supports several integration types with meaningfully different behavior: AWS_PROXY (Lambda proxy integration) passes the entire raw request to Lambda and expects a specific response shape back, doing minimal transformation in the gateway; AWS (non-proxy) integration lets you define VTL mapping templates that reshape the request before it reaches the backend and the response before it reaches the client, pushing transformation logic into the gateway configuration rather than application code; HTTP_PROXY passes requests through to an HTTP backend largely unmodified. The choice affects where transformation logic lives — and therefore where you debug it when something’s malformed.

What actually happens between “a client sends a request” and “your backend receives it.”

A request first hits API Gateway’s edge (for edge-optimized REST APIs, this is a CloudFront distribution AWS manages on your behalf; for regional APIs, requests land directly in the Region). The gateway resolves the request to a specific route or resource/method combination, then evaluates any configured authorizer — IAM, Cognito user pools, a Lambda authorizer, or JWT for HTTP APIs — before any integration logic runs. An authorization failure short-circuits the request entirely; the backend never sees it.

Once authorized, throttling is checked against the token bucket for the applicable scope (account-level default, per-method override, or per-API-key usage plan limit — the most restrictive applicable limit wins). If tokens are available, the request proceeds to the integration: for proxy integrations, the raw event is handed to the backend nearly as-is; for non-proxy integrations, the request-mapping template transforms it first. The backend’s response then optionally passes through a response-mapping template before being returned to the client, with the gateway also applying any configured gateway responses for error conditions it manages itself (like a 403 from a failed authorizer, which never reaches your backend’s own error-handling code).

graph TD
    A[Client Request] --> B[Edge or Regional Endpoint]
    B --> C[Route/Resource Resolution]
    C --> D{Authorizer Configured?}
    D -->|Yes| E[IAM / Cognito / Lambda / JWT Check]
    E -->|Fail| F[403 Gateway Response - Backend Never Called]
    E -->|Pass| G[Throttling Check - Token Bucket]
    D -->|No| G
    G -->|Throttled| H[429 Too Many Requests]
    G -->|Allowed| I{Integration Type}
    I -->|Proxy| J[Raw Event to Backend]
    I -->|Non-Proxy| K[Request Mapping Template - VTL]
    K --> J
    J --> L[Backend Processes Request]
    L --> M[Response Mapping Template - if non-proxy]
    M --> N[Response to Client]
        

The deployment model in API Gateway has a subtlety that trips up teams new to it: editing an API’s resources and methods in the console or via IaC does not affect live traffic until you explicitly create a deployment and associate it with a stage. A stage (like prod or staging) is a named, addressable snapshot of a deployment plus its own stage-specific configuration — throttling overrides, stage variables, logging settings — that persists independently of the underlying deployment.

Because a deployment is immutable and a stage is just a pointer, rollback in API Gateway is architecturally identical to the task-definition-revision pattern used elsewhere in AWS (ECS, Lambda versions) — repoint the stage to a previous deployment ID rather than reverting configuration changes.

API Gateway itself scales automatically and transparently — there’s no capacity to provision — but the practical performance ceiling in production is almost always the backend integration, not the gateway. A Lambda-backed API’s real throughput is bounded by Lambda concurrency limits, and a poorly configured reserved-concurrency setting on the backend function will produce throttling that looks like an API Gateway problem but originates entirely downstream.

Lambda authorizer caching is a significant, underused performance lever: by default, authorizer results can be cached per unique identity source (commonly a bearer token) for up to an hour, meaning repeated requests from the same client within the cache TTL skip the authorizer invocation entirely. Setting the TTL to zero to avoid stale-permission edge cases trades away this performance benefit entirely — every single request then pays the full authorizer Lambda invocation latency, which can dominate overall request latency at scale.

Coinbase has publicly discussed operating API Gateway at high transaction volume, citing careful tuning of per-method throttling overrides — rather than relying solely on account-level defaults — as essential to protecting downstream trading-engine capacity during traffic spikes, illustrating that throttling configuration is itself a capacity-protection tool for the backend, not just a client fairness mechanism.

API Gateway’s control and data planes are Regional, managed, multi-AZ services — you don’t design for its internal redundancy directly. The reliability decisions that matter are about backend integration failure handling and cross-Region strategy for the API layer itself.

A common reliability gap is treating API Gateway’s own availability as sufficient without configuring integration timeouts and retry/fallback behavior for backend failures — a Lambda function throwing consistently, or an HTTP backend timing out, produces 5xx responses from API Gateway regardless of the gateway’s own health, and without a configured fallback (a static response, a circuit-breaker pattern in the backend, or a secondary integration), clients simply see errors. For genuinely multi-Region resilience, teams deploy the same API definition to multiple Regions behind Route 53 with health-check-based failover or latency-based routing, since API Gateway itself doesn’t natively replicate an API across Regions the way S3 or DynamoDB Global Tables replicate data.

API Gateway supports four distinct authorization mechanisms with meaningfully different trust models: IAM authorization (the caller signs the request with AWS SigV4, suited to service-to-service calls within your own AWS environment), Cognito user pool authorizers (validates a JWT issued by Cognito, suited to end-user-facing applications), Lambda authorizers (fully custom logic, suited to integrating with an existing non-Cognito identity provider or implementing business-specific authorization rules), and native JWT authorizers on HTTP APIs (validates tokens from any OIDC-compliant issuer without a Lambda invocation at all, the lowest-latency option when it fits).

A frequently overlooked security layer is resource policies — much like ECR or S3, an API Gateway resource policy can restrict which source VPCs, VPC endpoints, or IP ranges can invoke the API at all, independent of any authorizer logic, which is the mechanism behind fully private APIs that are only reachable from within a specific VPC via an interface VPC endpoint, never traversing the public internet. AWS WAF, attachable to REST APIs and HTTP APIs, adds a further layer for common web exploit protection (SQL injection, XSS patterns) evaluated before requests reach the gateway’s own routing logic.

API Gateway emits per-stage CloudWatch metrics natively — Count, 4XXError, 5XXError, Latency, and IntegrationLatency — and the distinction between the last two matters for diagnosis: Latency measures the full round trip including the gateway’s own overhead, while IntegrationLatency measures only the backend’s response time, so a growing gap between them points to gateway-side processing (like a heavy VTL mapping template) rather than backend slowness.

Access logging, configured per stage, is opt-in and produces structured logs (JSON or a custom format string) that capture per-request details including which authorizer decision was made and which integration was invoked — this is the primary source for the “which requests were throttled or rejected before reaching the backend” investigation mentioned earlier, and should be enabled for any production stage, not just execution logging, since execution logging is coarser and more expensive at high volume.

A production API Gateway architecture typically defines the API via an OpenAPI specification checked into source control, deploying through CI/CD via CloudFormation or the Serverless Application Model rather than manual console configuration — this makes deployments themselves reviewable diffs and keeps the mapping between API version and backend Lambda version explicit and auditable.

graph LR
    SPEC[OpenAPI Spec in Source Control] --> CI[CI/CD Pipeline]
    CI -->|CloudFormation / SAM deploy| DEPLOY[New API Deployment]
    DEPLOY --> CANARY[Canary Stage - 10% Traffic]
    CANARY -->|validate metrics| PROMOTE{Promote?}
    PROMOTE -->|Yes| PROD[Full Production Stage]
    PROMOTE -->|No| ROLLBACK[Repoint Stage to Prior Deployment]
    PROD --> LAMBDA[Lambda / HTTP Backend]
    PROD --> WAF[AWS WAF Layer]
        

Private APIs, reachable only via an interface VPC endpoint, are increasingly the default pattern for internal service-to-service APIs in security-conscious organizations, replacing what used to be internally-routed REST calls over a shared VPC without gateway-level throttling, auth, or observability.

iRobot has publicly described migrating IoT device APIs to API Gateway’s WebSocket API type specifically to handle persistent, bidirectional connections from millions of devices, a use case REST or HTTP APIs’ request/response model cannot serve at all — illustrating that the API type choice is often dictated by the communication pattern itself, not preference.

Expedia has discussed using canary deployments on API Gateway stages as the primary safety mechanism for high-traffic booking APIs, citing the ability to validate error rates on a small percentage of live production traffic before full rollout as materially reducing the blast radius of backend regressions compared to their previous all-at-once deployment process.

Financial-services APIs commonly cite private API Gateway deployments behind interface VPC endpoints, combined with IAM authorization, as the pattern that satisfies internal network-segmentation requirements for service-to-service calls carrying regulated data, avoiding any path through the public internet even for internal traffic.