Amazon API Gateway Hands-On: REST vs HTTP APIs, Authorizers & Throttling

Every serverless API you build eventually needs a front door — something that terminates TLS, checks who is calling, refuses to be hammered, shapes the request, and hands it to your code. On AWS that front door is Amazon API Gateway, and the single most consequential decision you will make is which of its three flavors to use: a REST API (feature-rich, VTL transforms, API keys, caching, private endpoints), an HTTP API (cheaper, faster, JWT-native, the modern default for plain Lambda proxying), or a WebSocket API (stateful, two-way, for chat and live feeds). Choose the wrong one and you either pay 3.5× per request for features you never touch, or you box yourself into a flavor that cannot do the request transformation your legacy backend needs.

This is not a “click Create API” tutorial. API Gateway is a stack of gates — custom domain, WAF, authorizer, throttle bucket, request validator, mapping template, integration — and each gate has its own configuration surface, its own quota, and its own status code when it says no. A 403 can mean five completely different things depending on which gate emitted it. A 502 almost always means your Lambda returned the wrong shape. A 504 means you crossed the 29-second integration ceiling. Knowing which gate bit, from the status code and one log line, is the difference between a five-minute fix and a two-hour guess.

By the end you will be able to pick REST vs HTTP from a feature-and-cost matrix instead of a coin flip, wire every authorizer type (IAM SigV4, Cognito user pools, Lambda token/request, and HTTP-API JWT), throttle a spike gracefully with usage plans and API keys, reshape requests with VTL, front the API with a custom domain and WAF, and read the access log to find any failing hop. You will build two working APIs by hand — an HTTP API with a JWT authorizer and a REST API with an API-key usage plan, throttling and a mapping template — with aws CLI and Terraform, test authorized and throttled calls, then tear it all down.

What problem this solves

Without a managed API front door you are writing, in every service, the same undifferentiated plumbing: TLS termination, request parsing, auth token validation, rate limiting, per-client quotas, request/response logging, CORS handling, and a routing layer that maps URLs to handlers. That code is security-critical, tedious, and identical across teams — and when you hand-roll it on EC2 or containers you also own patching it, scaling it, and paying for it to idle overnight. Teams that skip the front door end up with each Lambda parsing its own JWTs, no consistent throttle, and a rate-limit story that is “hope nobody notices.”

API Gateway externalizes all of that into configuration. It terminates TLS at a custom domain with an ACM certificate, validates a JWT or a SigV4 signature or an API key before your code runs, throttles per-account, per-stage, per-method and per-client, validates the request body against a schema, transforms it with a template, invokes your Lambda or HTTP backend, logs every hop, and traces it with X-Ray — all billed per request, scaling from zero to tens of thousands of requests per second with no capacity to manage. The pain it removes is real, but it introduces its own: the wrong flavor is expensive, the proxy response shape is unforgiving, the 29-second timeout is a hard wall, and CORS-on-errors is a classic silent failure.

Here is the full request path this article covers, gate by gate, with what each gate does and its characteristic failure:

Learning objectives

By the end of this article you can:

• Choose REST vs HTTP vs WebSocket APIs from a feature and cost matrix, and justify the 3.5× price gap between REST and HTTP.
• Build resources, methods and integrations, and explain Lambda proxy vs non-proxy, HTTP proxy, AWS-service and mock integrations plus the exact proxy event/response shape.
• Manage stages, deployments and stage variables, and run a canary release that shifts a slice of traffic to a new deployment.
• Configure every authorizer — IAM SigV4, Cognito user pools, Lambda token/request (with result caching), and the HTTP-API JWT authorizer.
• Add request validation and VTL mapping templates, and read $input, $context, $util and $stageVariables.
• Throttle correctly with account/stage/method limits and usage plans + API keys for per-client quotas, and diagnose the 429.
• Enable caching (REST), CORS, WAF, custom domains, access/execution logging, X-Ray, and private APIs via interface endpoints.
• Work a 403/401/429/502/504 failure to root cause from the status code and a single log line.

Prerequisites & where this fits

You should have the AWS CLI v2 configured with credentials for a sandbox account, permission to create API Gateway, Lambda, IAM and (optionally) Cognito resources, and one working Lambda runtime (this article uses Node.js 20). Comfort with JSON, HTTP verbs, status codes and JWTs helps; no prior API Gateway experience is assumed. Terraform ≥ 1.5 with the aws provider is used for the IaC snippets.

This article is the front-door deep dive of the AWS serverless track. It sits one layer below the reference build in AWS Serverless Web Application Architecture: CloudFront, API Gateway, Lambda and DynamoDB End to End, goes far deeper on the API tier than the load-balancer comparison in AWS Load Balancers and API Gateway: ALB, NLB and API Gateway Compared, and feeds the pure event-driven work in AWS Lambda Patterns: Event-Driven Functions That Scale to Zero. If you have not yet shipped a function, do Your First AWS Lambda Function: A Hands-On Walkthrough first — this article assumes you can deploy a Lambda and read its logs.

Core concepts

Six mental models carry the whole service.

API Gateway is a pipeline of request/response phases, not a single hop. Every REST request passes through four phases: the method request (auth, validation, API key), the integration request (mapping template transforms it for the backend), the integration (the backend runs), and the integration response / method response (a template transforms the result back). Each phase can succeed or fail independently, and the phase decides the status code. HTTP APIs collapse this to a leaner path (route → authorizer → integration) with no VTL, which is exactly why they are faster and cheaper.

A stage is the only thing that is actually live. You build an API definition, then create a deployment (an immutable snapshot), then point a stage (prod, dev, $default) at that deployment. Throttling, logging, caching, WAF, X-Ray and stage variables all attach to the stage, not the API. Forgetting to redeploy after a change is the single most common “my fix isn’t live” bug on REST APIs — HTTP APIs can auto-deploy to sidestep it.

Authorization happens at the door, before your code. An authorizer verifies the caller and either lets the request through or returns 401/403 without invoking your integration. A JWT authorizer (HTTP API) checks a token’s signature, issuer, audience and expiry statelessly against a JWKS endpoint. A Lambda authorizer runs your code to return an IAM-style policy, cached by identity source. IAM (SigV4) authorization requires the caller to sign the request with AWS credentials. Your business logic never sees a raw credential.

Proxy integration trades control for simplicity. With Lambda proxy (AWS_PROXY), API Gateway passes the whole request to your function as a fixed JSON event and expects a fixed JSON response { statusCode, headers, body } back — no templates, but your function owns the entire HTTP contract. With non-proxy, you write VTL mapping templates to translate between HTTP and whatever your backend wants. Proxy is the default for new work; non-proxy is for legacy backends and fine-grained transformation.

Throttling is layered and additive. The account has a region-wide bucket (10,000 rps steady-state, 5,000 burst by default). On top of that you set stage and method limits, and per-client limits through usage plans + API keys. A request must pass every applicable bucket; the tightest one that trips returns 429. This is capacity planning as quota planning: know each ceiling before launch, not during one.

Everything is observable if you turn it on — and blind if you don’t. Access logs record one line per request ($context variables: status, latency, which authorizer, integration error). Execution logs record the internal phase-by-phase trace. X-Ray stitches the API-to-integration latency. None are on by default, and REST execution/access logging needs a one-time account-level CloudWatch Logs role ARN — the classic “why are there no logs” gotcha.

The moving parts, pinned down:

The request lifecycle, phase by phase (REST)

The three flavors: REST vs HTTP vs WebSocket

API Gateway is really three products sharing a console. Getting the choice right up front saves both money and rework.

Full feature matrix

REST vs HTTP cost, side by side

At 1 KB responses, no data-transfer surprises, us-east-1 list price:

REST tiers down (first 333M at $3.50, next to 667M at $2.80, next to 19B at $2.38, above at $1.51); HTTP is $1.00 for the first 300M then $0.90. The gap is why HTTP is the default for plain proxying — but note what you give up above: no usage plans, no caching, no VTL, no WAF, no request validation.

Which flavor — the decision table

Resources, methods and integrations

Integration types, end to end

Lambda proxy: the event shape (payload 1.0, REST)

Your handler receives this exact object:

Lambda proxy: the response shape (get this wrong = 502)

The single most common REST proxy bug: returning a raw object as body instead of a string, or omitting statusCode. API Gateway cannot serialize it and returns 502 Bad Gateway. HTTP APIs (payload 2.0) are forgiving — return a bare object and they default statusCode to 200 and stringify — but a returned object with a numeric body still 502s.

Proxy vs non-proxy — what you trade

HTTP API payload format 2.0 vs 1.0

Wiring a method (REST) and a route (HTTP)

REST needs the four-step method chain; HTTP needs one route:

# REST: create resource, method, proxy integration, deploy
REST_ID=$(aws apigateway create-rest-api --name orders-rest \
  --endpoint-configuration types=REGIONAL --query id --output text)
ROOT=$(aws apigateway get-resources --rest-api-id "$REST_ID" \
  --query 'items[0].id' --output text)
RES=$(aws apigateway create-resource --rest-api-id "$REST_ID" \
  --parent-id "$ROOT" --path-part items --query id --output text)
aws apigateway put-method --rest-api-id "$REST_ID" --resource-id "$RES" \
  --http-method GET --authorization-type NONE --api-key-required
aws apigateway put-integration --rest-api-id "$REST_ID" --resource-id "$RES" \
  --http-method GET --type AWS_PROXY --integration-http-method POST \
  --uri "arn:aws:apigateway:$AWS_REGION:lambda:path/2015-03-31/functions/$FN_ARN/invocations"
aws apigateway create-deployment --rest-api-id "$REST_ID" --stage-name prod

# HTTP: one-shot quick-create wires route + integration + $default stage
aws apigatewayv2 create-api --name orders-http --protocol-type HTTP \
  --target "$FN_ARN"        # auto-creates $default route + auto-deploy stage

# Terraform: HTTP API route to a Lambda proxy
resource "aws_apigatewayv2_api" "http" {
  name          = "orders-http"
  protocol_type = "HTTP"
}
resource "aws_apigatewayv2_integration" "lambda" {
  api_id                 = aws_apigatewayv2_api.http.id
  integration_type       = "AWS_PROXY"
  integration_uri        = aws_lambda_function.api.invoke_arn
  payload_format_version = "2.0"
}
resource "aws_apigatewayv2_route" "get_items" {
  api_id    = aws_apigatewayv2_api.http.id
  route_key = "GET /items"
  target    = "integrations/${aws_apigatewayv2_integration.lambda.id}"
}

Stages, deployments and stage variables

Stage settings that matter

Stage variables — one API, many backends

A stage variable is a name=value on the stage, referenced as ${stageVariables.name} in an integration URI, a Lambda alias, or a mapping template. The classic use: prod points at the :prod Lambda alias, dev at :dev, from one API definition.

Gotcha: a stage variable used in a Lambda integration URI that has no matching lambda:InvokeFunction permission for that alias produces a 500 with Invalid permissions on Lambda function. And an unresolved ${stageVariables.x} (variable not set on the stage) surfaces as a 500 — always confirm the variable exists on the stage you called.

Canary releases (REST)

A canary shifts a percentage of stage traffic to a new deployment while the rest stays on the current one — same URL, split at the stage.

aws apigateway update-stage --rest-api-id "$REST_ID" --stage-name prod \
  --patch-operations op=replace,path=/canarySettings/percentTraffic,value=10
# promote when metrics look good:
aws apigateway update-stage --rest-api-id "$REST_ID" --stage-name prod \
  --patch-operations op=copy,from=/canarySettings/deploymentId,path=/deploymentId \
                     op=remove,path=/canarySettings

Custom domains, endpoint types and ACM

Endpoint types (REST)

The number-one custom-domain 403/handshake failure: putting the ACM cert in the wrong region. Edge-optimized custom domains need the cert in us-east-1 regardless of where the API runs; regional domains need it in the same region as the API. HTTP APIs are regional only.

Custom domain components

# Regional custom domain + base-path mapping (REST)
aws apigateway create-domain-name --domain-name api.example.com \
  --regional-certificate-arn "$CERT_ARN" \
  --endpoint-configuration types=REGIONAL --security-policy TLS_1_2
aws apigateway create-base-path-mapping --domain-name api.example.com \
  --rest-api-id "$REST_ID" --stage prod --base-path v1

resource "aws_apigatewayv2_domain_name" "api" {
  domain_name = "api.example.com"
  domain_name_configuration {
    certificate_arn = aws_acm_certificate.api.arn   # same region for HTTP API
    endpoint_type   = "REGIONAL"
    security_policy  = "TLS_1_2"
  }
}
resource "aws_apigatewayv2_api_mapping" "v1" {
  api_id      = aws_apigatewayv2_api.http.id
  domain_name = aws_apigatewayv2_domain_name.api.id
  stage       = aws_apigatewayv2_stage.prod.id
  api_mapping_key = "v1"
}

Authorization: five ways to say who you are

The authorizer matrix

IAM (SigV4) authorization

Set authorization-type AWS_IAM on the method; the caller signs with AWS credentials, and API Gateway checks an execute-api:Invoke allow. Best for service-to-service and internal tools where callers already hold IAM credentials.

aws apigateway update-method --rest-api-id "$REST_ID" --resource-id "$RES" \
  --http-method GET --patch-operations op=replace,path=/authorizationType,value=AWS_IAM
# caller must sign; e.g. awscurl / SigV4 SDK:
awscurl --service execute-api --region "$AWS_REGION" "https://$REST_ID.execute-api.$AWS_REGION.amazonaws.com/prod/items"

Cognito user pool authorizer (REST)

Lambda authorizers — token vs request

A Lambda authorizer returns an IAM policy document plus an optional context map that flows to $context.authorizer.<key> (and into a proxy event’s requestContext.authorizer). The Resource in the policy can be a wildcard so the cached Allow covers sibling methods; scope it tighter for least privilege.

// REQUEST Lambda authorizer (HTTP API simple response)
exports.handler = async (event) => {
  const token = (event.headers.authorization || "").replace("Bearer ", "");
  const ok = token === process.env.SHARED_SECRET;      // demo: verify a JWT for real
  return { isAuthorized: ok, context: { tenant: "acme" } };
};

JWT authorizer (HTTP API)

The modern default: no code, stateless, works with any OIDC issuer.

aws apigatewayv2 create-authorizer --api-id "$HTTP_ID" --name jwt-auth \
  --authorizer-type JWT --identity-source '$request.header.Authorization' \
  --jwt-configuration Audience="$APP_CLIENT_ID",Issuer="https://cognito-idp.$AWS_REGION.amazonaws.com/$POOL_ID"

resource "aws_apigatewayv2_authorizer" "jwt" {
  api_id           = aws_apigatewayv2_api.http.id
  authorizer_type  = "JWT"
  identity_sources = ["$request.header.Authorization"]
  name             = "jwt-auth"
  jwt_configuration {
    audience = [var.app_client_id]
    issuer   = "https://cognito-idp.${var.region}.amazonaws.com/${var.pool_id}"
  }
}

Request validation and VTL mapping templates (REST)

Request validation

A request validator checks the request before integration, returning 400 on failure with no backend cost.

VAL=$(aws apigateway create-request-validator --rest-api-id "$REST_ID" \
  --name body-and-params --validate-request-body --validate-request-parameters \
  --query id --output text)
aws apigateway put-method --rest-api-id "$REST_ID" --resource-id "$RES" \
  --http-method POST --authorization-type NONE \
  --request-validator-id "$VAL" --request-models application/json=OrderModel

VTL: the variables you actually use

## Integration request template: HTTP body → SQS SendMessage form
Action=SendMessage&MessageBody=$util.urlEncode($input.body)&MessageAttribute.1.Name=tenant&MessageAttribute.1.Value.StringValue=$context.authorizer.tenant&MessageAttribute.1.Value.DataType=String

Throttling, usage plans and API keys

The four throttle layers (they stack)

A request must satisfy every applicable bucket; the tightest one that empties returns 429 Too Many Requests with x-amzn-ErrorType: ThrottlingException (or LimitExceededException when a usage-plan quota is exhausted). Throttling is a token bucket: burst is the bucket size (max concurrent), rate is the refill per second.

Usage plans + API keys (REST only)

An API key is an identifier and metering handle, not a security control — never use it as authentication. Pair it with a real authorizer. A key sent to a method whose apiKeyRequired is false is simply ignored (no metering, no throttle by plan).

KEY_ID=$(aws apigateway create-api-key --name acme --enabled --query id --output text)
PLAN=$(aws apigateway create-usage-plan --name bronze \
  --throttle rateLimit=100,burstLimit=200 \
  --quota limit=1000000,period=MONTH \
  --api-stages apiId="$REST_ID",stage=prod --query id --output text)
aws apigateway create-usage-plan-key --usage-plan-id "$PLAN" \
  --key-id "$KEY_ID" --key-type API_KEY

resource "aws_api_gateway_usage_plan" "bronze" {
  name = "bronze"
  api_stages { api_id = aws_api_gateway_rest_api.orders.id  stage = "prod" }
  throttle_settings { rate_limit = 100  burst_limit = 200 }
  quota_settings   { limit = 1000000  period = "MONTH" }
}
resource "aws_api_gateway_api_key" "acme" { name = "acme" }
resource "aws_api_gateway_usage_plan_key" "acme" {
  key_id        = aws_api_gateway_api_key.acme.id
  key_type      = "API_KEY"
  usage_plan_id = aws_api_gateway_usage_plan.bronze.id
}

Throttle vs quota

Caching (REST)

A stage cache stores integration responses keyed by the request, cutting backend load and latency. It is REST-only and billed per hour by size.

Cache-key mistakes are a data-leak class of bug: if you cache a per-user response but do not include the user identity in the cache key, user B can be served user A’s cached response. Only cache safely-shared responses, or include the authorizing header/claim in the cache key.

CORS, WAF, logging, X-Ray and private APIs

CORS — REST vs HTTP

The nastiest CORS bug: preflight passes but the error response (a 401/429/500) lacks Access-Control-Allow-Origin, so the browser shows “CORS error” for what is actually an auth or throttle failure. On REST, add the header to the relevant gateway responses, not just the method.

# HTTP API native CORS
aws apigatewayv2 update-api --api-id "$HTTP_ID" \
  --cors-configuration AllowOrigins="https://app.example.com",AllowMethods="GET,POST,OPTIONS",AllowHeaders="authorization,content-type",MaxAge=300

WAF (REST only)

A WAFv2 WebACL attaches to a REST stage (regional scope). HTTP APIs have no native WAF — front them with CloudFront + WAF. Common managed rules: AWSManagedRulesCommonRuleSet, AWSManagedRulesAmazonIpReputationList, plus a rate-based rule.

aws wafv2 associate-web-acl --web-acl-arn "$WEBACL_ARN" \
  --resource-arn "arn:aws:apigateway:$AWS_REGION::/restapis/$REST_ID/stages/prod"

Logging: access vs execution

{ "requestId":"$context.requestId", "ip":"$context.identity.sourceIp",
  "status":"$context.status", "err":"$context.error.message",
  "intErr":"$context.integrationErrorMessage", "authErr":"$context.authorizer.error",
  "latency":"$context.responseLatency", "intLatency":"$context.integration.latency" }

The one-time gotcha: REST execution and access logging to CloudWatch requires an account-level IAM role ARN set in API Gateway → Settings (cloudWatchRoleArn). If it is unset, logging silently does nothing. Set it once per region.

X-Ray and private APIs

Enable X-Ray active tracing on the stage to trace API-Gateway-to-integration latency. A private API (PRIVATE endpoint type, REST only) is reachable only through an interface VPC endpoint (com.amazonaws.<region>.execute-api) and needs a resource policy allowing that endpoint:

Architecture at a glance

The diagram traces one request left to right through every gate. A client presents a JWT and/or an x-api-key; the request lands on a custom domain (ACM cert, base-path mapping), passes WAF (REST only), hits the prod stage, is checked by the authorizer (JWT/Lambda/Cognito/IAM), metered by the throttle + usage plan bucket, validated and optionally VTL-mapped, then handed to the Lambda proxy or an HTTP backend (via VPC link), which reads/writes DynamoDB — with access + execution logs, X-Ray traces and a CloudWatch alarm watching 5XXError and p99 Latency. Each numbered badge marks where a specific status code is emitted, so a failure names its own gate.

Real-world scenario

Meridian Tickets, a mid-size events platform, ran a public REST API on API Gateway fronting 40 Lambdas. Their problems were textbook. First, cost: at 220 million requests/month they paid roughly $770/month for the API tier alone on REST, even though 34 of the 40 endpoints were plain Lambda proxies with no VTL, no caching, and no API keys. Second, a launch-day meltdown: when a headline act went on sale, traffic spiked to ~14,000 rps and callers got a wall of 429s — the account default of 10,000 rps they had never raised. Third, a mystery 403 on their partner integration that took a day to diagnose.

The migration was surgical. They split the API into two: the six partner-facing, metered, cached endpoints stayed on REST (usage plans gave partners a 1M-requests/month quota and a per-partner x-api-key, and a 300-second cache on the read-heavy /events endpoint cut Lambda invocations by 63%). The 34 simple proxy endpoints moved to an HTTP API with a Cognito JWT authorizer — dropping those from $3.50 to $1.00 per million and shaving ~40 ms of p50 latency off each call. Blended, the API bill fell to about $300/month, a 61% cut, and p99 latency on the migrated routes improved because the VTL pipeline was gone.

They fixed the spike by requesting an account quota increase to 20,000 rps and adding a usage plan throttle so a single partner could not consume the whole bucket; a stage-level rate of 12,000 rps with 6,000 burst absorbed the on-sale surge, and the cache soaked the read amplification. The partner 403 turned out to be the classic pair: the partner had been calling /v1 but the base-path mapping was only configured for the root, and separately their SDK dropped the x-api-key header on redirect so the apiKeyRequired method rejected them. Both were visible in one access-log line ($context.error.responseType = MISSING_AUTHENTICATION_TOKEN for the path, API_KEY_MISSING for the header) — logs they had never enabled because the account CloudWatch role ARN was unset. Enabling logging first would have turned a one-day hunt into a five-minute read. The lesson they wrote on the wall: pick the flavor per endpoint, raise the quota before the launch, and turn logs on before you need them.

Advantages and disadvantages

REST wins when you need metering, caching, VTL, WAF, private or edge-optimized endpoints. HTTP wins for cheap, fast, JWT-fronted proxying — the majority of internal microservices. WebSocket wins only when you genuinely need server push. When request rates get truly massive and features are minimal, compare against an ALB → Lambda front door, which is flat-rate per LCU rather than per request.

Hands-on lab

You will build two APIs on a free-tier-friendly account: (A) an HTTP API fronting a Lambda with a JWT authorizer backed by Cognito, and (B) a REST API with an API-key usage plan, method throttling, and a request-validation + mapping touch. Then you will test authorized, unauthorized and throttled calls, and tear everything down.

⚠️ Cost note: Lambda, API Gateway (first 1M REST / 1M HTTP calls) and Cognito (first 10k/50k MAUs) are free-tier eligible. A REST cache and a custom domain are not free — this lab skips the cache and domain; enable them only if you accept the hourly/cert cost. Tear down at the end regardless.

Step 0 — variables and a Lambda both APIs share

export AWS_REGION=ap-south-1
export ACCT=$(aws sts get-caller-identity --query Account --output text)

# Minimal execution role
cat > trust.json <<'EOF'
{ "Version":"2012-10-17","Statement":[{"Effect":"Allow",
  "Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}
EOF
ROLE_ARN=$(aws iam create-role --role-name apigw-lab-fn \
  --assume-role-policy-document file://trust.json --query Role.Arn --output text)
aws iam attach-role-policy --role-name apigw-lab-fn \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
sleep 10   # let the role propagate

# The handler (returns a correct proxy response shape)
mkdir -p fn && cat > fn/index.mjs <<'EOF'
export const handler = async (event) => {
  const claims = event.requestContext?.authorizer?.jwt?.claims
              || event.requestContext?.authorizer?.claims || {};
  return {
    statusCode: 200,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ ok: true, user: claims.sub || "anon", path: event.rawPath || event.path })
  };
};
EOF
( cd fn && zip -q ../fn.zip index.mjs )
FN_ARN=$(aws lambda create-function --function-name apigw-lab \
  --runtime nodejs20.x --handler index.handler --role "$ROLE_ARN" \
  --zip-file fileb://fn.zip --query FunctionArn --output text)

Expected: FN_ARN prints an ARN like arn:aws:lambda:ap-south-1:123456789012:function:apigw-lab.

Step 1 — Cognito user pool (for the JWT authorizer)

POOL_ID=$(aws cognito-idp create-user-pool --pool-name apigw-lab-pool \
  --query UserPool.Id --output text)
CLIENT_ID=$(aws cognito-idp create-user-pool-client --user-pool-id "$POOL_ID" \
  --client-name lab-client --explicit-auth-flows ALLOW_USER_PASSWORD_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --query UserPoolClient.ClientId --output text)
# a test user with a permanent password
aws cognito-idp admin-create-user --user-pool-id "$POOL_ID" --username lab@example.com \
  --message-action SUPPRESS
aws cognito-idp admin-set-user-password --user-pool-id "$POOL_ID" \
  --username lab@example.com --password 'Lab-Passw0rd!' --permanent

Step 2 — HTTP API + JWT authorizer + route

HTTP_ID=$(aws apigatewayv2 create-api --name lab-http --protocol-type HTTP \
  --query ApiId --output text)
INT_ID=$(aws apigatewayv2 create-integration --api-id "$HTTP_ID" \
  --integration-type AWS_PROXY --integration-uri "$FN_ARN" \
  --payload-format-version 2.0 --query IntegrationId --output text)
AUTH_ID=$(aws apigatewayv2 create-authorizer --api-id "$HTTP_ID" --name jwt \
  --authorizer-type JWT --identity-source '$request.header.Authorization' \
  --jwt-configuration Audience="$CLIENT_ID",Issuer="https://cognito-idp.$AWS_REGION.amazonaws.com/$POOL_ID" \
  --query AuthorizerId --output text)
aws apigatewayv2 create-route --api-id "$HTTP_ID" --route-key 'GET /me' \
  --target "integrations/$INT_ID" \
  --authorization-type JWT --authorizer-id "$AUTH_ID"
aws apigatewayv2 create-stage --api-id "$HTTP_ID" --stage-name '$default' --auto-deploy
aws lambda add-permission --function-name apigw-lab --statement-id http-invoke \
  --action lambda:InvokeFunction --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:$AWS_REGION:$ACCT:$HTTP_ID/*/*/me"
HTTP_URL="https://$HTTP_ID.execute-api.$AWS_REGION.amazonaws.com"

Step 3 — test the JWT authorizer (401 then 200)

# no token → 401
curl -s -o /dev/null -w "%{http_code}\n" "$HTTP_URL/me"          # expect 401

# get an ID token, then call authorized
ID_TOKEN=$(aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH \
  --client-id "$CLIENT_ID" \
  --auth-parameters USERNAME=lab@example.com,PASSWORD='Lab-Passw0rd!' \
  --query 'AuthenticationResult.IdToken' --output text)
curl -s -H "Authorization: $ID_TOKEN" "$HTTP_URL/me"             # expect {"ok":true,"user":"<sub>",...}

Expected: first call prints 401; second prints the JSON body with your Cognito sub. If the second returns 401, the token aud must equal the app client ID and the issuer must match the pool exactly.

Step 4 — REST API with API key, usage plan, throttle and validation

REST_ID=$(aws apigateway create-rest-api --name lab-rest \
  --endpoint-configuration types=REGIONAL --query id --output text)
ROOT=$(aws apigateway get-resources --rest-api-id "$REST_ID" --query 'items[0].id' --output text)
RES=$(aws apigateway create-resource --rest-api-id "$REST_ID" --parent-id "$ROOT" \
  --path-part items --query id --output text)
# GET /items requires an API key
aws apigateway put-method --rest-api-id "$REST_ID" --resource-id "$RES" \
  --http-method GET --authorization-type NONE --api-key-required
aws apigateway put-integration --rest-api-id "$REST_ID" --resource-id "$RES" \
  --http-method GET --type AWS_PROXY --integration-http-method POST \
  --uri "arn:aws:apigateway:$AWS_REGION:lambda:path/2015-03-31/functions/$FN_ARN/invocations"
aws apigateway create-deployment --rest-api-id "$REST_ID" --stage-name prod
aws lambda add-permission --function-name apigw-lab --statement-id rest-invoke \
  --action lambda:InvokeFunction --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:$AWS_REGION:$ACCT:$REST_ID/*/GET/items"

# API key + usage plan with a tight throttle so we can trip a 429
KEY_VALUE=$(aws apigateway create-api-key --name lab-key --enabled \
  --query value --output text)
KEY_ID=$(aws apigateway get-api-keys --name-query lab-key --include-values \
  --query 'items[0].id' --output text)
PLAN=$(aws apigateway create-usage-plan --name lab-plan \
  --throttle rateLimit=1,burstLimit=1 --quota limit=1000,period=DAY \
  --api-stages apiId="$REST_ID",stage=prod --query id --output text)
aws apigateway create-usage-plan-key --usage-plan-id "$PLAN" \
  --key-id "$KEY_ID" --key-type API_KEY
REST_URL="https://$REST_ID.execute-api.$AWS_REGION.amazonaws.com/prod/items"

Step 5 — test the API key (403) and the throttle (429)

# missing key → 403
curl -s -o /dev/null -w "%{http_code}\n" "$REST_URL"                    # expect 403

# with the key → 200
curl -s -H "x-api-key: $KEY_VALUE" "$REST_URL"                          # expect 200 JSON

# hammer it — rate 1/burst 1 means most of a burst is 429
for i in $(seq 1 10); do
  curl -s -o /dev/null -w "%{http_code} " -H "x-api-key: $KEY_VALUE" "$REST_URL"
done; echo                                                             # expect a mix of 200 and 429

Expected: no key → 403; with key → 200; the loop prints several 429s once the burst bucket empties. That is the usage-plan throttle doing its job.

Step 6 — turn on access logging (see the gates)

LG=$(aws logs create-log-group --log-group-name /apigw/lab-rest 2>/dev/null; \
     echo "arn:aws:logs:$AWS_REGION:$ACCT:log-group:/apigw/lab-rest")
aws apigateway update-stage --rest-api-id "$REST_ID" --stage-name prod \
  --patch-operations \
   op=replace,path=/accessLogSettings/destinationArn,value="$LG" \
   op=replace,path=/accessLogSettings/format,value='{"status":"$context.status","err":"$context.error.responseType","key":"$context.identity.apiKeyId"}'
# (Requires the one-time account CloudWatch role ARN — set it if logs stay empty:)
# aws apigateway update-account --patch-operations op=replace,path=/cloudwatchRoleArn,value=arn:aws:iam::$ACCT:role/<apigw-cloudwatch-role>

Step 7 — teardown (deletes everything)

aws apigatewayv2 delete-api --api-id "$HTTP_ID"
aws apigateway delete-usage-plan-key --usage-plan-id "$PLAN" --key-id "$KEY_ID"
aws apigateway delete-usage-plan --usage-plan-id "$PLAN"
aws apigateway delete-api-key --api-key "$KEY_ID"
aws apigateway delete-rest-api --rest-api-id "$REST_ID"
aws logs delete-log-group --log-group-name /apigw/lab-rest 2>/dev/null || true
aws lambda delete-function --function-name apigw-lab
aws cognito-idp delete-user-pool --user-pool-id "$POOL_ID"
aws iam detach-role-policy --role-name apigw-lab-fn \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
aws iam delete-role --role-name apigw-lab-fn

Verify teardown: aws apigateway get-rest-apis --query "items[?name=='lab-rest']" returns [], and aws apigatewayv2 get-apis --query "Items[?Name=='lab-http']" returns [].

Common mistakes & troubleshooting

This is the section you will reread at 2 a.m. Work top to bottom: read the status code, then the one access-log field that disambiguates it, then apply the fix.

The playbook

Status / error-code reference

Decision table — from a symptom to a cause

The three nastiest, in prose

The malformed proxy response (502). New engineers write return { body: { ok: true } } and API Gateway returns 502 with “Malformed Lambda proxy response” in the execution log. The contract is strict: statusCode is required (REST 1.0), and body must be a string — so JSON.stringify it. HTTP API payload 2.0 forgives a bare object (wraps it 200 + stringified), which is why the same handler behaves differently across flavors and masks the bug until you move it to REST.

CORS masking auth/throttle failures. Your OPTIONS preflight is configured, the happy path works, but a 401 or 429 shows up in the browser as a generic “CORS error” because the error response has no Access-Control-Allow-Origin. On REST APIs, gateway responses (DEFAULT_4XX, DEFAULT_5XX, UNAUTHORIZED, THROTTLED) are separate from your method responses and need the CORS headers added explicitly. Until you do, every backend error looks like a frontend/CORS problem and you debug the wrong layer.

The 29-second wall (504). API Gateway integrations hard-cap at 29 seconds by default (raisable via a service-quota increase on REST/regional, but most accounts run the default). A report endpoint that scans a big table, a third-party call that occasionally hangs, or a cold-starting downstream can cross it and return 504 even though the Lambda eventually finished — you pay for the full Lambda run and the client got nothing. The fix is architectural: return a 202 Accepted with a job id, do the work asynchronously (SQS + worker Lambda, or Step Functions), and let the client poll or receive a webhook.

Best practices

• Default to HTTP APIs; reach for REST only for a feature you actually use — usage plans/API keys, caching, VTL, request validation, WAF, private or edge-optimized endpoints.
• Raise the account throttle quota before a launch, and layer stage/method/usage-plan limits so one client cannot drain the shared bucket.
• Turn on access + execution logging and X-Ray on day one — set the account CloudWatch role ARN once per region; you cannot debug what you did not log.
• Never use an API key as authentication. Pair keys (metering/quota) with a real authorizer (JWT/Cognito/IAM/Lambda).
• Return the exact proxy response shape (statusCode + string body) and test it on the flavor you deploy to, not just locally.
• Add CORS headers to gateway responses, not only to the happy-path method, so errors surface correctly in the browser.
• Validate requests at the gateway with models/validators to reject junk with a cheap 400 before it reaches Lambda.
• Cache only safely-shared responses, and if a response is per-user, include the user identity in the cache key — or don’t cache it.
• Use stage variables (or aliases) for environment routing, and remember the matching lambda:InvokeFunction permission per alias.
• Keep sync work under a few seconds; anything that can approach 29 s belongs on the async path.
• Scope the authorizer policy Resource and keep the result TTL short enough that a revoked token stops working quickly.
• Version with base-path mappings (/v1, /v2) on a stable custom domain rather than leaking the execute-api hostname.

Security notes

• Least privilege on the integration role — the Lambda’s execution role, and any AWS-service integration credentials role, should grant only the specific actions/resources needed.
• Prefer JWT/Cognito/IAM over long-lived API keys. Keys are for metering; rotate them, and disable a compromised key immediately (update-api-key --patch-operations op=replace,path=/enabled,value=false).
• Encrypt the response cache (Encrypt cache data) if it holds any sensitive payloads, and lock the cache-key set so responses cannot bleed across users.
• Put WAF in front (REST directly; HTTP via CloudFront) with the common rule set, the IP reputation list, and a rate-based rule; log to a WAF logging destination.
• Use resource policies to constrain a REST API to specific source IPs, VPCs (aws:SourceVpce) or accounts; make internal APIs private so they have no public URL at all.
• Set minimum TLS 1.2 on custom domains, and use mTLS for partner APIs that must present a client certificate.
• Log identity, not secrets — capture apiKeyId/sub in access logs, never the raw token or key value.
• Turn on CloudTrail for API Gateway control-plane changes so an unexpected authorizer or stage edit is auditable.

Cost & sizing

What drives the bill: request count × per-million rate (flavor-dependent), data transfer out, optional cache hours (REST), and any WAF and CloudWatch Logs ingestion. Caching and custom domains (via the ACM cert, which is free, but the edge-optimized path uses CloudFront) can add cost; the requests themselves dominate at scale.

Right-sizing rules: move plain-proxy endpoints to HTTP for the 71% saving; add a REST cache only when the backend is the bottleneck and the response is cacheable (a 300 s TTL on a hot read can cut Lambda cost more than the cache costs); and compare an ALB → Lambda front door when volume is very high and you need almost none of API Gateway’s features — LCU-based pricing can beat per-request at scale.

Interview & exam questions

1. When would you choose a REST API over an HTTP API? When you need a REST-only feature: API keys and usage plans, response caching, VTL request/response transformation, request validation via models, WAF directly on the API, a private (VPC) endpoint, or an edge-optimized endpoint. Otherwise HTTP is cheaper and faster. (SAA-C03, DVA-C02)

2. Explain the difference between Lambda proxy and non-proxy integration. Proxy (AWS_PROXY) passes the entire request to Lambda as a fixed event and expects a fixed {statusCode, headers, body} response; no mapping templates. Non-proxy (AWS) uses VTL templates to map the request to the backend and the response back, giving fine control at the cost of complexity. (DVA-C02)

3. A Lambda-backed endpoint returns 502. What’s the most likely cause? A malformed proxy response — usually the function returned a non-string body or omitted statusCode. Fix by returning statusCode and a JSON.stringify-ed string body. (DVA-C02)

4. How do you meter and limit a specific partner’s usage? REST usage plans + API keys: create an API key, attach it to a usage plan with a throttle (rate/burst) and a quota (per day/week/month), associate the plan with the API+stage, and set apiKeyRequired on the methods. HTTP APIs cannot do this. (SAA-C03)

5. What are the throttle layers and their default? Account (region-wide, 10,000 rps steady / 5,000 burst by default), stage, method, and per-key usage plan. A request must pass every applicable bucket; the tightest returns 429. (SAA-C03, ANS-C01)

6. How does a JWT authorizer differ from a Cognito user pool authorizer? JWT authorizers are HTTP-API-only and work with any OIDC issuer (validating iss/aud/exp/scopes statelessly against a JWKS endpoint). Cognito user pool authorizers are REST-only and specific to Cognito pools. Both avoid running your code. (DVA-C02)

7. Why did my API return 504 even though the Lambda finished? The integration exceeded the 29-second timeout, so API Gateway returned 504 while the Lambda kept running (and billing). Move long work to an async pattern (SQS/Step Functions) and return 202. (DVA-C02)

8. How do you customize the error returned when the request body is invalid? Attach a request validator + model (JSON Schema) to the method; invalid bodies get a 400 (BAD_REQUEST_BODY) whose message you can customize via the BAD_REQUEST_BODY gateway response. (DVA-C02)

9. What’s the correct place for the ACM certificate on a custom domain? For edge-optimized custom domains, the cert must be in us-east-1; for regional custom domains (and all HTTP APIs), in the same region as the API. Wrong region → handshake/403 failures. (SAA-C03, ANS-C01)

10. How do you make an API reachable only from inside a VPC? Use a REST private API (PRIVATE endpoint type), create an interface VPC endpoint for execute-api, and add a resource policy allowing that aws:SourceVpce. No public URL exists. (ANS-C01, SCS-C02)

11. Where do throttling, logging and caching attach — the API or the stage? The stage. Deployments are immutable snapshots; the stage points at one and carries throttle, logging, cache, WAF, X-Ray and stage variables. (DVA-C02)

12. Your browser shows a CORS error on a call that returns 401. Why? The preflight is fine, but the 401 error response lacks Access-Control-Allow-Origin. On REST APIs, add CORS headers to the relevant gateway responses (UNAUTHORIZED/DEFAULT_4XX), not just the method. (DVA-C02)

Quick check

1. Which two features are REST-only that most often force you off HTTP APIs?
2. What is the default account request throttle (steady and burst)?
3. What must a Lambda proxy response include to avoid a 502?
4. Which authorizer type is HTTP-API-only, and what does it validate?
5. Where must the ACM certificate live for an edge-optimized custom domain?

Answers

1. Usage plans + API keys and response caching (also VTL, request validation, WAF, private/edge endpoints). 2. 10,000 rps steady-state, 5,000 burst, region-wide. 3. An integer statusCode and a string body (JSON must be stringified). 4. The JWT authorizer — validates a token’s signature, issuer, audience and expiry (and optional scopes) against a JWKS endpoint. 5. us-east-1, regardless of the API’s region.

Glossary

Next steps

• Build the full stack this front door sits on in AWS Serverless Web Application Architecture: CloudFront, API Gateway, Lambda and DynamoDB End to End.
• Compare API Gateway against layer-4/7 load balancers in AWS Load Balancers and API Gateway: ALB, NLB and API Gateway Compared.
• Wire the async paths a 29-second timeout pushes you toward in AWS Lambda Patterns: Event-Driven Functions That Scale to Zero.
• If you have not shipped a function yet, start with Your First AWS Lambda Function: A Hands-On Walkthrough.