API Gateway & Lambda Integration
Key concepts
REST vs HTTP APIs
Lambda proxy integration
API throttling and quotas
Caching responses
Custom authorizers
Overview
Amazon API Gateway is a fully managed service for creating, publishing, and securing APIs at scale. Paired with AWS Lambda, it is the backbone of serverless request handling: API Gateway receives the HTTP request, handles auth, throttling, and caching, then invokes a Lambda function that returns the response. No servers to manage, and it scales with traffic automatically.
This pairing is high-yield on the SAA-C03 exam. You should know when to choose REST APIs versus HTTP APIs, how Lambda proxy integration passes the request through, how throttling and usage plans protect your backend, when stage caching helps, and which authorizer fits a given auth requirement.
Managed Front Door for Serverless APIs
API Gateway is the entry point that authenticates, throttles, caches, and routes requests to a backend (usually Lambda), so your function code stays focused on business logic rather than cross-cutting concerns.
Know REST vs HTTP API trade-offs, Lambda proxy (AWS_PROXY) integration shape, the 29-second integration timeout, account throttling defaults (10,000 RPS steady, 5,000 burst), usage plans plus API keys for per-client limits, stage caching, and the authorizer options (IAM, Lambda, Cognito, JWT).
Key Concepts
REST APIs vs HTTP APIs
Choosing the API Type
HTTP APIs are cheaper and lower latency with a leaner feature set, and support JWT authorizers, Lambda authorizers, and CORS. REST APIs offer the full feature set: API keys and usage plans, request and response validation and transformation, response caching, AWS WAF, private endpoints, and edge-optimized delivery. A third type, WebSocket APIs, supports real-time two-way communication.
REST API vs HTTP API
| Feature | REST API | HTTP API |
|---|---|---|
| Relative cost | Higher | Lower (about 70% less) |
| API keys and usage plans | Yes | No |
| Request/response transformation | Yes | No |
| Response caching | Yes | No |
| AWS WAF integration | Yes | No |
| Private endpoints | Yes | No |
| JWT authorizer | No | Yes |
| Best for | Full-featured, regulated APIs | Simple, low-latency proxies |
Lambda Proxy Integration
Proxy vs Non-Proxy
With Lambda proxy integration (AWS_PROXY), API Gateway passes the entire request (path, headers, query string, body) to Lambda as one event, and Lambda must return a response object with statusCode, headers, and body. With non-proxy integration you instead use mapping templates to reshape requests and responses. Proxy is simpler and most common.
// Lambda must return this structure for proxy integration
{
"statusCode": 200,
"headers": {
"Content-Type": "application/json",
"Access-Control-Allow-Origin": "*"
},
"body": "{\"orderId\":\"12345\",\"status\":\"confirmed\"}"
}Endpoint Types
REST API Endpoint Types
| Type | How It Routes | Use Case |
|---|---|---|
| Edge-optimized | Through CloudFront edge locations | Geographically dispersed clients |
| Regional | Directly in one Region | Clients in the same Region |
| Private | Only from a VPC via interface endpoint | Internal APIs, no public access |
Throttling and Usage Plans
Protecting the Backend
API Gateway throttles with a token bucket. The account-level default is 10,000 requests per second steady-state with a 5,000 request burst. You can set per-stage and per-method limits, and use usage plans with API keys to give each client its own rate, burst, and quota (for example 1,000 requests per day per key).
Request flow through throttling:
├── Account limit: 10,000 RPS steady, 5,000 burst (soft, can raise)
├── Stage/method limit: optional tighter caps
└── Usage plan (per API key)
├── Rate: requests per second
├── Burst: bucket size
└── Quota: requests per day/week/month
Exceeding a limit returns HTTP 429 Too Many Requests.Caching
Stage Caching (REST APIs)
REST APIs support per-stage response caching from 0.5 GB to 237 GB. The default TTL is 300 seconds (configurable 0 to 3600). Cache keys can include request parameters so different inputs cache separately. Caching cuts backend calls and latency for read-heavy endpoints. You can encrypt cache data and invalidate entries with a header.
Authorizers
Authorization Options
| Authorizer | How It Works | Best For |
|---|---|---|
| IAM (SigV4) | Signed requests, IAM policies | Service-to-service, internal callers |
| Lambda authorizer | Custom function returns allow/deny policy | Custom token or header logic |
| Cognito user pools | Validates Cognito-issued tokens | User sign-in for REST APIs |
| JWT authorizer | Validates OIDC/OAuth JWTs | HTTP APIs with an identity provider |
Best Practices
1. Default to HTTP APIs for simple proxies
├── Lower cost and latency
└── Move to REST APIs when you need keys, caching, WAF, or private endpoints
2. Use proxy integration unless you need transformation
└── Keeps the contract simple; reshape only when required
3. Protect backends with usage plans
├── Per-client rate, burst, and quota via API keys
└── Prevents one client from overwhelming Lambda
4. Cache idempotent GETs
└── Stage caching reduces latency and backend load
5. Keep handlers under the 29-second integration timeout
└── Offload long work to Step Functions or async patternsCommon Pitfalls
Pitfall 1: Expecting Long-Running Requests
Mistake: Designing an endpoint that runs work taking more than 29 seconds.
Why it fails: API Gateway has a 29-second integration timeout; the caller gets a 504.
Correct Approach: Return quickly and run long work asynchronously (Step Functions, SQS plus a worker), then let the client poll or receive a callback.
Pitfall 2: Treating API Keys as Authentication
Mistake: Using API keys to authenticate or authorize users.
Why it fails: API keys identify a client for usage plans and throttling; they are not a security control.
Correct Approach: Authenticate with Cognito, a Lambda authorizer, IAM, or JWT, and use API keys only for rate limiting and quotas.
Pitfall 3: Forgetting the Lambda Proxy Response Shape
Mistake: Returning a raw object from Lambda under proxy integration.
Why it fails: Proxy integration requires statusCode, headers, and a string body, so a malformed return yields a 502.
Correct Approach: Return the full proxy response structure, with body serialized as a string.
Test Your Knowledge
A startup needs a low-cost, low-latency public API that simply proxies requests to Lambda and validates JWTs from an existing identity provider. Which API type fits best?
An API endpoint occasionally triggers a backend job that takes about 90 seconds. Clients report 504 errors. What is the correct design change?
A company offers a public REST API and wants each customer limited to 10,000 requests per day with a per-second rate cap. What should they configure?
Related Services
Quick Reference
Key Limits
API Gateway Limits
| Resource | Default |
|---|---|
| Account throttle (steady) | 10,000 RPS (soft) |
| Account throttle (burst) | 5,000 requests |
| Integration timeout | 29 seconds (max) |
| Payload size | 10 MB |
| Stage cache size | 0.5 GB to 237 GB |
| Default cache TTL | 300 seconds |
Common CLI Commands
# Create an HTTP API backed by a Lambda (quick create)
aws apigatewayv2 create-api \
--name orders-api \
--protocol-type HTTP \
--target arn:aws:lambda:us-east-1:123456789012:function:Orders
# Create a usage plan with throttle and quota
aws apigateway create-usage-plan \
--name "standard-tier" \
--throttle burstLimit=200,rateLimit=100 \
--quota limit=10000,period=DAY
# Enable stage caching
aws apigateway update-stage \
--rest-api-id abc123 --stage-name prod \
--patch-operations op=replace,path=/cacheClusterEnabled,value=true