AWS API Gateway: Technical Reference & Operational Intelligence

Executive Summary

AWS API Gateway is a managed API service that handles authentication, rate limiting, and routing. Critical cost difference: REST APIs cost $3.50/million requests vs HTTP APIs at $0.90-$1.00/million requests (71% cheaper). Default limits: 10,000 requests/second per account ($35K/month at max on REST APIs).

Service Types & Decision Matrix

Feature	REST API	HTTP API	WebSocket API
Cost per million requests	$3.50	$0.90-$1.00	$1.00
Use when	Need full features	Need speed/cost optimization	Real-time communication required
Authentication	IAM, Cognito, API Keys, Lambda	IAM, Cognito, JWT, Lambda	IAM, Lambda only
Built-in caching	✅ ($0.02/GB/hour)	❌	❌
Request validation	✅	❌	❌
AWS WAF protection	✅	❌	❌
Private endpoints	✅ (VPC Links required)	❌	❌
Performance	Standard	Up to 71% faster	Persistent connections

Critical Configuration Requirements

Production Settings That Work

• Choose HTTP APIs over REST APIs unless you specifically need caching, request validation, or AWS WAF
• Use regional endpoints instead of edge-optimized (simpler, faster, cheaper)
• Enable CloudWatch logging before production - costs extra but essential for debugging
• Set custom domains early - execute-api URLs are ugly and can't be changed

Resource Requirements

• Time investment: 2-4 hours for basic setup, 1-2 days for production-ready configuration
• Expertise needed: Basic AWS knowledge, understanding of HTTP/REST principles
• Additional costs: ACM certificates (free), CloudWatch logs ($0.50/GB), caching ($0.02/GB/hour)

Critical Failure Modes & Solutions

502 Errors (Common)

Root causes:

• Lambda cold starts (500ms+ delay)
• Backend timeouts (30-second limit)
• Lambda function crashes

Solutions:

• Use provisioned concurrency ($41.67/month per GB)
• Implement proper error handling in Lambda
• Monitor CloudWatch logs for "Task timed out" messages

CORS Errors (Extremely Common)

Failure pattern: Browser shows generic CORS error, actual cause unclear
Hidden requirements:

• Enable CORS on both resource AND methods
• Handle OPTIONS method separately for preflight
• Set Access-Control-Allow-Credentials: true when using authentication
• Don't use * for origins with credentials

"Missing Authentication Token" Error

Reality: Usually means wrong URL, not authentication issue
Common causes:

1. Wrong stage path (/prod/users vs /users)
2. HTTP method not deployed
3. Forgot to deploy after changes
4. Custom domain base path mapping broken

Cost Explosions

Warning signs:

• Edge-optimized APIs can double CloudFront costs
• Caching fees apply whether used or not ($0.02/GB/hour)
• Traffic spikes can cause $2K+ overnight bills

Performance Thresholds & Bottlenecks

Critical Limits

• Payload limit: 6MB (hard limit)
• Timeout: 30 seconds for Lambda integrations
• Default throttling: 10,000 requests/second per account
• Cold start impact: 500ms+ for first request, 8+ seconds for Java Spring Boot

Real-World Performance

• CloudWatch logs delay: 5-10 minutes to appear
• Cache propagation: 5-10 minutes for invalidation
• Custom domain setup: ~20 minutes if everything works
• VPC cold starts: 15+ seconds if ENIs aren't warm

Hidden Costs & Trade-offs

Edge-Optimized Reality

• Marketing claim: Better global performance
• Reality: Often doubles CloudFront bill without significant benefit
• When it helps: Truly global user base with latency-sensitive operations

Caching Economics

• Cost: $0.02/GB/hour whether used or not
• Break-even: Only valuable for frequently accessed, slowly changing data
• Hidden cost: Manual cache invalidation adds operational overhead

Lambda Integration Costs

• Provisioned concurrency: $10.80/month for 1GB function running 24/7
• When worth it: APIs with strict latency requirements
• Alternative: Periodic pings to keep functions warm (cheaper but less reliable)

Integration Patterns & Limitations

Direct AWS Service Integration

Supports: DynamoDB, S3, SNS (without Lambda)
Benefits: Lower latency and cost
Limitations: No custom logic, limited transformations
Best for: Simple CRUD operations

VPC Integration

Requires: Network Load Balancer (additional cost)
Complexity: High - requires VPC Links configuration
Availability: REST APIs only
Use case: Private services that shouldn't be internet-accessible

Monitoring & Debugging Strategy

Essential Metrics to Track

1. Count: Total request volume (billing impact)
2. Latency: Response time breakdown
3. 4XXError/5XXError: Error rates
4. ThrottleCount: Rate limiting hits

X-Ray Tracing

• Availability: REST APIs only
• Cost: Additional charges apply
• Value: Essential for distributed debugging
• Setup time: 30 minutes for basic configuration

Migration & Breaking Changes

From REST to HTTP APIs

Benefits: 71% cost reduction, better performance
Losses: Caching, request validation, AWS WAF
Migration effort: 1-2 days for typical API
Compatibility: Not drop-in replacement

Common Migration Gotchas

• Custom domain certificates need reconfiguration
• CloudFormation templates require complete rewrite
• Monitoring dashboards break (different metric names)

Decision Criteria

Choose REST APIs when:

• Need built-in caching
• Require request validation
• Need AWS WAF protection
• Working with private VPC services

Choose HTTP APIs when:

• Cost optimization is priority
• Building simple proxy APIs
• Don't need advanced features
• Performance is critical

Choose WebSocket APIs when:

• Real-time communication required
• Chat applications, live dashboards
• Gaming backends
• Connection persistence needed

Production Readiness Checklist

Before Going Live

• Enable CloudWatch logging
• Set up billing alarms ($100, $500, $1000)
• Configure custom domains with ACM certificates
• Test CORS configuration thoroughly
• Implement proper error handling in Lambda functions
• Set up monitoring dashboards
• Plan for traffic spikes (request limit increases)

Operational Monitoring

• CloudWatch metrics for latency and errors
• Billing alerts for cost control
• Log analysis for debugging patterns
• Regular performance testing under load

Community Intelligence

What Documentation Doesn't Tell You

• Deployment stages confuse everyone - "prod" and "production" are different
• CORS error messages are intentionally unhelpful
• Cache invalidation is manual and slow
• VPC integration adds significant complexity
• Default settings will fail in production scenarios

Support Quality

• AWS Support requires 20-question interrogation for limit increases
• Community solutions often better than official documentation
• GitHub issues contain more practical information than AWS docs
• Stack Overflow has battle-tested CORS solutions