Amazon API Gateway

By the end of this lesson you will be able to

• Explain what Amazon API Gateway does as the front door of a serverless API (client → API Gateway → Lambda → DynamoDB), and list what it takes off your hands: routing, stages, security, API keys and usage plans, throttling, validation, transformation, caching, OpenAPI import, WebSocket.
• Choose between the three API types, REST, HTTP and WebSocket, from their features and prices.
• Connect an API to a Lambda function (proxy or custom), an HTTP backend, an AWS service such as Kinesis Data Streams, or a mock, and fix the missing permission behind a 500.
• Choose an endpoint type, edge-optimized, Regional or private, and put a custom domain on it with the ACM certificate in the right Region.
• Protect an API with IAM (SigV4), Cognito user pools, Lambda authorizers, resource policies and AWS WAF, and tell 401 from 403.
• Use the limits that shape designs (29-second integration timeout, 10 MB payload, 10,000 requests per second per account, cache TTL 300 s up to 3,600 s) and choose between API Gateway, an ALB and a Lambda function URL.

#Why an API needs a front door

A mobile app, a website or a partner’s server never talks to your database directly. It calls an API: a set of HTTPS addresses such as GET /products/42 or POST /orders. Something has to receive those calls, check who is calling, stop floods, send each call to the right code and return the answer. On a server-based design that is your web server plus a pile of middleware you write and patch.

Amazon API Gateway is a fully managed service that does this job. The notes call it the front door between clients (mobile apps, websites) and your backend (Lambda, EC2, DynamoDB). It helps you create, publish, maintain, monitor and secure APIs, and you pay per call, with no servers and nothing to pay while nobody calls.

#A serverless API, end to end

The classic serverless API has four boxes: the client sends HTTPS requests to API Gateway, which forwards them (as a proxy) to a Lambda function, which does CRUD on a DynamoDB table. None of the four needs a server you manage, all four scale with traffic, and the bill drops to almost nothing at 4 a.m. The notes’ first exam trick: a question that says “serverless architecture” or “expose AWS Lambda as a RESTful API” wants API Gateway.

Lambda itself is lessons 15.1 and 15.2; DynamoDB is lesson 15.4. Here we follow the request through the front door, first when everything works, then the five common ways it fails.

#What API Gateway does for you

Behind the one word “gateway” sit many features. These are the ones the exam and real projects use:

#Stages and deployments

On a REST API, changing a method does nothing for clients until you deploy it to a stage. A deployment is a snapshot of the API; a stage points at one deployment and adds its own settings: throttling, caching, logging, WAF, and stage variables (key–value pairs, for example lambdaAlias=prod, so the prod stage calls the prod alias of the function and dev calls dev). A canary setting on a stage sends a small percentage of traffic to a new deployment before everyone gets it. HTTP APIs can also auto-deploy every change to a stage, which is handy for dev.

The notes: stages let you run several versions or environments (dev, test, prod) of the same API side by side. Combined with Lambda aliases (lesson 15.1), that is how you release a new version without breaking the app already in people’s phones.

#REST, HTTP or WebSocket API

API Gateway offers three API types. The exam mostly says “API Gateway” and means a REST API; real projects should choose deliberately.

The rule of thumb from the AWS documentation: choose REST when you need API keys, per-client throttling, request validation, WAF, caching or private endpoints; choose HTTP when you do not, because it is cheaper and faster.

#WebSocket APIs in one paragraph

A WebSocket API keeps a connection open between the client and API Gateway. The client sends JSON messages; a route selection expression such as $request.body.action sends each message to a route (sendMessage, updateLocation), plus the special routes $connect (authorize and store the connection ID, for example in DynamoDB), $disconnect (clean up) and $default. To push a message to a client, the backend calls the @connections callback URL with that client’s connection ID. A connection lasts at most 2 hours and closes after 10 minutes idle; a message can be up to 128 KB (in 32 KB frames). Chat apps, live dashboards, multiplayer games and the ride-sharing map that moves the rider’s icon all fit here.

#Integrations: what sits behind the door

An integration connects a route or method to a backend. The slides list three high-level kinds, and REST APIs add a fourth.

1. Lambda function. The easy way to expose a REST API backed by Lambda.
   • Lambda proxy (AWS_PROXY): the whole request (path, query string, headers, body, caller identity) becomes the event; the function returns statusCode, headers and a string body. This is what almost everyone uses.
   • Lambda custom (non-proxy, AWS): mapping templates (written in VTL) reshape the request into the event and the function’s result into the HTTP response. Older and more work, but the function stays unaware of HTTP.
2. HTTP. Forward to any HTTP endpoint: an ALB in front of EC2 or containers, an internal API on premises, a partner’s URL. Why put API Gateway in front of something that already works? To add rate limiting, caching, authentication and API keys without touching it. A backend inside a VPC (a private ALB or NLB) is reached through a VPC link.
3. AWS service. Call any AWS API directly, with no Lambda in between: SendMessage to SQS, start a Step Functions workflow, PutRecord into Kinesis Data Streams, PutItem into DynamoDB. API Gateway signs the call with an IAM role you give it. Why? To get authentication, a public HTTPS address and rate control in front of the service, without code. HTTP APIs offer the same idea as ready-made “first-class” integrations for SQS, EventBridge, Kinesis Data Streams and Step Functions, among others.
4. Mock (REST only): API Gateway answers by itself with a fixed response. Useful while the backend is not ready, or for a CORS preflight.

The slides’ AWS service example is a clickstream pipeline: client → API Gateway → Kinesis Data Streams → Data Firehose → S3 (.json files). It ingests events at any rate with no function of yours running (lessons 13.5 and 13.6).

#Endpoint types and custom domains

An API always lives in one Region. The endpoint type decides how clients reach it.

Two clarifications the slides leave out. First, edge-optimized does not cache your responses at the edge; it only shortens the network path (API caching is a separate stage setting). Second, edge-optimized uses a CloudFront distribution that AWS manages and you cannot configure; if you want WAF on CloudFront, geo restriction or your own cache rules, use a Regional endpoint behind your own distribution. Interface endpoints themselves are lesson 22.2.

#Custom domain names and the ACM certificate

Nobody wants to print abc123.execute-api.ap-southeast-1.amazonaws.com on a partner contract. A custom domain name such as api.shop.example points at one or more APIs and stages (through API mappings, for example /v1 → API A stage prod). HTTPS for it needs a certificate from AWS Certificate Manager (lesson 21.4), and the Region of that certificate is a favourite exam detail:

• Edge-optimized custom domain → the certificate must be in us-east-1 (N. Virginia), because the CloudFront distribution behind it is global and CloudFront reads certificates from there.
• Regional custom domain → the certificate must be in the same Region as the API.
• Then create a Route 53 alias (A or AAAA) record, or a CNAME, that points the name at the domain’s target (a CloudFront name for edge-optimized, a Regional d-…execute-api name for Regional). Alias vs CNAME is lesson 8.2.

Since late 2024, private REST APIs can have custom domain names too, shared to VPC endpoints through an access association. In 2025 API Gateway also added dual-stack (IPv4 and IPv6) endpoints (March, for REST, HTTP and WebSocket APIs and custom domains) and routing rules on custom domains (June, REST APIs only: send traffic to an API by header or path, for example for a gradual v1 → v2 move). These are side notes; the exam asks about the certificate Region.

#Security: who may call the API

The slides list three ways to authenticate users; the full menu is a little longer.

Read the status codes right. 401 Unauthorized means “who are you?”: no token, or an invalid or expired one. 403 Forbidden means “I know who you are, and no”: a Lambda authorizer returned Deny, IAM did not allow execute-api:Invoke, a resource policy or WAF blocked the source. Both are returned before your backend runs, so they cost you no Lambda time.

#Throttling, usage plans and caching

#Throttling: four layers

Throttling protects your backend and your bill from floods. API Gateway uses a token bucket: a steady rate (requests per second) plus a burst (the bucket size, how many can arrive at once). Over the limit, callers get 429 Too Many Requests and should retry with exponential backoff. Limits apply in this order, and the tightest wins:

1. Per client (REST only): the usage plan limit for that client’s API key, optionally per method.
2. Per method: a stage’s method-level limits, for example POST /orders at 200 per second.
3. Per stage: the default for every method in the stage.
4. Per account and Region: by default 10,000 requests per second with a burst bucket of 5,000, shared by all REST, HTTP and WebSocket APIs in the account in that Region (some newer Regions start at 2,500). You can request an increase in Service Quotas.

The notes put the default at 10,000 per second; the detail that bites in production is the word shared: one API’s spike can make every other API in the account throttle. Set stage and method limits so no single API can eat the whole account limit.

#Usage plans and API keys

A usage plan (REST only) says how much a client may use: a throttle (rate and burst) and a quota (requests per day, week or month). A client gets an API key, the key is attached to a plan, and the plan is attached to API stages. Methods that need a key have API key required turned on. Over the rate, the client gets 429; over the quota, 429 with “Limit Exceeded” until the period resets. The notes’ exam trick: “usage plans”, “API keys” or “throttling third-party developers” mean API Gateway (and specifically a REST API).

#Caching responses

The notes’ second exam trick: “improve API performance and reduce backend load” → enable API caching. A REST API stage can have a cache:

• The TTL is 300 seconds (5 minutes) by default, configurable from 0 (no caching) to 3,600 seconds.
• The cache key is the method and path plus the parameters you choose (query strings, headers). Choose them carefully: forgetting a parameter serves one user’s answer to another.
• The cache costs money per hour by size, from 0.5 GB to 237 GB, whether it is used or not; a single cached response can be up to 1 MB.
• You can flush the whole stage cache, and you can override caching per method. A client can skip the cache for one request with Cache-Control: max-age=0 if it has the IAM permission execute-api:InvalidateCache; require that permission, or anyone can bypass your cache.
• HTTP and WebSocket APIs have no built-in cache; put CloudFront in front if you need one.

Caching trades freshness for speed. A five-minute TTL on prices during a flash sale can show the old price; pick the TTL from how stale the data may be, and flush when you must.

#The limits that shape designs

The 29-second timeout is the one exam questions love. The trap behind it: when API Gateway gives up and returns 504, the Lambda function keeps running to its own timeout (up to 15 minutes) and is billed, but its answer goes nowhere. Lambda’s timeout should be shorter than the API’s.

#Follow one request through the checks

Put it all together. Choose the API type, the token, the client’s traffic, the cache, how long the backend takes and the body size, then press the button and see which check stops the request, with what status code, after how long, and whether you paid for a Lambda run.

#API Gateway vs Application Load Balancer

Both receive HTTP traffic from clients and pass it to a backend. The notes’ comparison, with the corrections the inventory found:

#What goes wrong

#API Gateway in system design

• Default serverless front door: client → API Gateway → Lambda → DynamoDB, with Cognito for users (the to-do app and blog designs in lesson 15.8).
• HTTP API by default, REST API when you need keys, plans, caching, validation, WAF or a private endpoint. Many companies run both: a cheap HTTP API for their own app and a REST API for partners.
• Keep synchronous calls short: under a few seconds. Anything longer goes through a queue or a workflow, and the client polls or listens on a WebSocket.
• Direct service integrations (SQS, Kinesis, Step Functions, DynamoDB) remove “glue” Lambda functions, which saves money, latency and concurrency.
• Protect in layers: WAF at the edge, authorizers for identity, usage plans per client, stage and method throttles, reserved concurrency on the functions behind (lesson 15.2), so one flood cannot drain everything.
• Cache what many people ask for, and only that; pick keys and TTLs per method.
• Stages per environment, Lambda aliases per stage, canary releases for risky changes; define everything in OpenAPI or infrastructure as code.
• Observe: alarms on 5XXError, Latency and IntegrationLatency; access logs; X-Ray for slow paths.

#Try it yourself

An HTTP API in front of a function, then a REST API with a usage plan and a cache, in ap-southeast-1, account 111122223333. Outputs are shortened.

# 1. Quick-create an HTTP API with a Lambda proxy integration (one route, $default stage, auto-deploy)
aws apigatewayv2 create-api --name shop-http-example --protocol-type HTTP \
  --target arn:aws:lambda:ap-southeast-1:111122223333:function:products-example
#   { "ApiId": "a1b2c3d4e5", "ApiEndpoint": "https://a1b2c3d4e5.execute-api.ap-southeast-1.amazonaws.com", ... }

# Quick create adds the invoke permission; with a manual setup you must add it yourself:
aws lambda add-permission --function-name products-example \
  --statement-id apigw-invoke --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:ap-southeast-1:111122223333:a1b2c3d4e5/*"

curl -s https://a1b2c3d4e5.execute-api.ap-southeast-1.amazonaws.com/products/42
#   {"id":"42","name":"Panjabi","price":2450}

# 2. A REST API (Regional) for partners: create a usage plan with throttle and quota
aws apigateway create-usage-plan --name free-example \
  --throttle burstLimit=20,rateLimit=10 --quota limit=10000,period=MONTH \
  --api-stages apiId=x9y8z7w6v5,stage=prod
#   { "id": "pl4n1d", "name": "free-example", "throttle": {"burstLimit": 20, "rateLimit": 10.0}, ... }

aws apigateway create-api-key --name shop-a-example --enabled
#   { "id": "k3y1d", "value": "Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90", ... }
aws apigateway create-usage-plan-key --usage-plan-id pl4n1d --key-id k3y1d --key-type API_KEY

# 40 calls in one second from the free key: some come back 429
for i in $(seq 40); do curl -s -o /dev/null -w "%{http_code} " \
  -H "x-api-key: Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78St90" \
  https://x9y8z7w6v5.execute-api.ap-southeast-1.amazonaws.com/prod/track/7781 & done; wait
#   200 200 200 ... 429 429 200 429 ...

# 3. Turn on a 0.5 GB cache on the prod stage, TTL 600 s for all methods
aws apigateway update-stage --rest-api-id x9y8z7w6v5 --stage-name prod --patch-operations \
  op=replace,path=/cacheClusterEnabled,value=true \
  op=replace,path=/cacheClusterSize,value=0.5 \
  op=replace,path=/*/*/caching/enabled,value=true \
  op=replace,path=/*/*/caching/ttlInSeconds,value=600

# Data changed? Flush the stage cache
aws apigateway flush-stage-cache --rest-api-id x9y8z7w6v5 --stage-name prod

# 4. Check the account throttle limits for the Region
aws apigateway get-account --query throttleSettings
#   { "burstLimit": 5000, "rateLimit": 10000.0 }

Watch the Count, 4XXError, 5XXError, CacheHitCount and CacheMissCount metrics in CloudWatch while you run the loop. Delete the cache when you are done: it is billed every hour it exists.

#Summary

Key takeaways

• API Gateway is the managed front door of an API: routing, stages, security, API keys and usage plans, throttling, validation, transformation, caching, OpenAPI import, SDK generation, WebSocket, pay per request. Classic serverless API: client → API Gateway → Lambda → DynamoDB. “Expose Lambda as a RESTful API” → API Gateway.
• Three API types: REST (all features: keys, usage plans, cache, validation, WAF, private endpoints; about $3.50 per million), HTTP (cheaper at about $1.00 per million, faster, JWT authorizer, Regional only, 30 s), WebSocket (two-way, server push, $connect/$disconnect, @connections).
• Integrations: Lambda proxy (function returns statusCode, headers, body) or custom with mapping templates; HTTP backends (ALB, on premises, VPC link) to add rate limiting, caching, auth and keys; AWS service APIs directly (Kinesis Data Streams → Firehose → S3, SQS, Step Functions) with an IAM role; mock. Lambda needs a resource policy for apigateway.amazonaws.com.
• Endpoints: edge-optimized (REST default, via CloudFront edges, still one Region, no edge caching), Regional (same-Region clients, or your own CloudFront), private (interface VPC endpoint + resource policy). Custom domain certificate in us-east-1 for edge-optimized, in the API’s Region for Regional; Route 53 alias or CNAME.
• Security: IAM/SigV4 for internal callers, Cognito user pools for external users (JWT checked by API Gateway), Lambda authorizer for your own logic (returns an IAM policy, cached 300 s by default), resource policies and WAF by source. 401 = who are you; 403 = not allowed. API keys are not authentication.
• Throttling: token bucket, 10,000 rps + 5,000 burst per account per Region, shared by all APIs; stage, method and per-client usage plan limits; over limit → 429. Throttling is not DDoS protection: use WAF and Shield.
• Caching (REST only): TTL 300 s default, 0–3,600 s, 0.5–237 GB billed hourly, per-stage, flushable; “improve performance and reduce backend load” → enable caching.
• Limits: 29 s integration timeout (504, the function keeps running; raise only on Regional/private REST; streaming up to 15 min since 2025), 10 MB payload (6 MB for Lambda), so long jobs go async and big files go to S3 via presigned URLs. CORS errors → enable CORS.
• API Gateway vs ALB: per request + API management + cache + IAM/Cognito/Lambda authorizers vs hourly + LCUs, load balancing for EC2/containers (and Lambda), Cognito/OIDC on HTTPS listeners. “Monolith on EC2/containers” → ALB; “usage plans, API keys, throttle third-party developers” → API Gateway; one function, one URL → function URL.

Self-check: Amazon API Gateway32 questions