Amazon API Gateway

What Is API Gateway?

API Gateway is AWS's managed service for building, deploying, and managing APIs. It sits between your clients and your backend (Lambda, ECS, HTTP endpoints) and handles routing, authentication, throttling, CORS, request/response transformation, and TLS termination.

You have three flavors:

	REST API	HTTP API	WebSocket API
Cost	$3.50/million requests	$1.00/million requests	$1.00/million messages
Features	Full-featured (usage plans, API keys, WAF, caching, request validation)	Lightweight (JWT auth, Lambda/HTTP integrations)	Bidirectional real-time
Latency	Higher (~30ms overhead)	Lower (~10ms overhead)	N/A
Best for	Enterprise APIs needing full control	Most new APIs	Chat, notifications, live updates

REST API vs HTTP API

Use HTTP API when:

You want the cheapest, fastest option
JWT authorization (Cognito, Auth0) is sufficient
You don't need request validation, usage plans, or API key management
You're building a new API with no legacy constraints

Use REST API when:

You need WAF integration for IP blocking, rate limiting by rule
You need usage plans and API keys for third-party consumers
You need request/response transformation (VTL templates)
You need built-in caching
You need resource policies for cross-account access

For most new projects, HTTP API is the right default. It's 70% cheaper and faster.

Authorization Patterns

JWT Authorizer (HTTP API)

API Gateway validates the JWT token directly. No Lambda needed:

Validates signature against JWKS
Checks expiration
Verifies issuer and audience
Passes claims to the backend in the request context

Works with Cognito, Auth0, Okta, or any OIDC provider.

Lambda Authorizer

A Lambda function that receives the token/request and returns an IAM policy. Use when:

You need custom authorization logic
Your tokens aren't standard JWTs
You need to look up permissions from a database
You want to cache auth decisions (5-minute TTL)

IAM Authorization

Requests are signed with AWS Signature V4. Use for service-to-service communication within AWS where both caller and API are in your account.

Cognito Authorizer (REST API)

REST API has a native Cognito integration that validates tokens and provides user pool claims.

Throttling and Rate Limiting

API Gateway provides two levels of throttling:

Account-level: 10,000 requests/second across all APIs in a region (soft limit)
Stage/route-level: Configure per-route throttling to protect backends

Default: 10,000 rps (account-wide)
Per-route: You can set lower limits to protect slow backends
Burst: Up to 5,000 concurrent requests

For REST APIs, usage plans give you per-API-key quotas. Useful when you expose APIs to third-party developers.

Custom Domains

Map your own domain (api.mycompany.com) to your API:

Get a TLS certificate in ACM (us-east-1 for edge-optimized, same region for regional)
Create a custom domain name in API Gateway
Map API stages to base path mappings
Point DNS (Route 53 CNAME/A-Alias) to the API Gateway domain

Multiple APIs can share one custom domain using base path mappings:

api.mycompany.com/orders → Orders API
api.mycompany.com/users → Users API
api.mycompany.com/payments → Payments API

Architecture Patterns

Single Lambda per route

Each API route maps to its own Lambda function. Maximum isolation, independent deployments, granular IAM permissions. More operational overhead (many functions to manage).

Monolithic Lambda

One Lambda handles all routes. Simpler deployment, but larger package, coarser IAM permissions, and coupled deployments.

Lambda per domain/resource

Middle ground. One Lambda per resource group (orders, users, payments). Each handles all CRUD operations for its domain. Balanced isolation and simplicity.

API Gateway + VPC Link + ALB/NLB

Route API Gateway traffic to containers in a VPC without exposing them publicly. Good for migrating existing services behind API Gateway without rewriting them as Lambda.

CDK Example

import { HttpApi, HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import { HttpJwtAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';

const api = new HttpApi(this, 'Api', {
  apiName: 'my-api',
  corsPreflight: {
    allowOrigins: ['https://myapp.com'],
    allowMethods: [HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT, HttpMethod.DELETE],
    allowHeaders: ['Authorization', 'Content-Type'],
  },
});

const authorizer = new HttpJwtAuthorizer('JwtAuth', 
  `https://cognito-idp.${region}.amazonaws.com/${userPool.userPoolId}`, {
  jwtAudience: [appClient.userPoolClientId],
});

api.addRoutes({
  path: '/orders/{id}',
  methods: [HttpMethod.GET],
  integration: new HttpLambdaIntegration('GetOrder', getOrderFn),
  authorizer,
});

Cost Considerations

HTTP API: $1.00 per million requests + data transfer
REST API: $3.50 per million requests + data transfer + cache (if enabled)
No charge for failed auth (JWT authorizer rejects before invocation)
REST API caching: $0.02–$3.80/hour depending on cache size

At 10M requests/month: HTTP API = $10, REST API = $35. The 3.5x difference adds up.