Amazon API Gateway

Amazon API Gateway is a fully managed service for creating, publishing, and managing APIs at any scale. It acts as the "front door" for applications to access backend services — Lambda functions, HTTP endpoints, or other AWS services. API Gateway handles authentication, throttling, caching, request/response transformation, and monitoring, letting you focus on business logic.

---

API Gateway Types

AWS offers three types of API Gateway, each designed for different use cases:

Type	Protocol	Use Case	Pricing Model
REST API	HTTP (REST)	Full-featured APIs with request validation, caching, API keys, usage plans	Per request + data transfer
HTTP API	HTTP (REST)	Low-latency, cost-optimised APIs with simpler features	Per request (up to 71% cheaper)
WebSocket API	WebSocket	Real-time, two-way communication (chat, dashboards, gaming)	Per message + connection minutes

REST API vs HTTP API Decision Matrix

Requirement	Use
API keys / usage plans	REST API
Request/response validation	REST API
Caching	REST API
WAF integration	REST API
Private API endpoints	REST API
Lowest cost + simple proxy	HTTP API
JWT authorisation (built-in)	HTTP API
Fastest latency	HTTP API
WebSocket support	WebSocket API

---

Core Concepts

Resources and Methods

API Gateway models your API as a tree of resources (URL paths) with methods (HTTP verbs):

graph TD
  root["/ (root)"]
  root --> users["/users — GET: List users"]
  users --> userId["/{userId} — GET: Get user by ID<br/>PUT: Update user<br/>DELETE: Delete user"]
  users --> userOrders["/{userId}/orders — GET: List user's orders"]
  root --> orders["/orders — POST: Create order"]
  orders --> orderId["/{orderId} — GET: Get order by ID"]
  root --> health["/health — GET: Health check"]

Stages

A stage is a named reference to a deployment of your API — think of it as an environment:

Stage	URL	Purpose
dev	https://abc123.execute-api.eu-west-1.amazonaws.com/dev	Development testing
staging	https://abc123.execute-api.eu-west-1.amazonaws.com/staging	Pre-production validation
prod	https://abc123.execute-api.eu-west-1.amazonaws.com/prod	Production traffic

Deployments

A deployment is a snapshot of your API configuration. You create a deployment and associate it with a stage to make changes live.

---

Request / Response Flow

sequenceDiagram
  participant Client
  participant API as API Gateway
  participant Backend
  Client->>API: HTTP Request
  API->>Backend: Authentication
  API->>Backend: Request Validation
  API->>Backend: Request Transformation
  API->>Backend: Invoke Backend
  Backend-->>API: Backend Response
  API->>API: Response Transformation
  API->>API: Caching (if enabled)
  API-->>Client: HTTP Response

Each step in this pipeline is configurable. You can validate request bodies, transform headers, cache responses, and apply throttling — all without writing backend code.

---

Authentication and Authorisation

API Gateway supports multiple authentication mechanisms:

IAM Authorisation

Requests are signed with AWS Signature Version 4. Best for service-to-service calls within AWS.

Lambda Authorisers

A custom Lambda function validates the token or request parameters and returns an IAM policy:

export const handler = async (event) => {
  const token = event.authorizationToken;

  try {
    const decoded = verifyJWT(token);
    return generatePolicy(decoded.sub, 'Allow', event.methodArn);
  } catch {
    return generatePolicy('anonymous', 'Deny', event.methodArn);
  }
};

function generatePolicy(principalId, effect, resource) {
  return {
    principalId,
    policyDocument: {
      Version: '2012-10-17',
      Statement: [{
        Action: 'execute-api:Invoke',
        Effect: effect,
        Resource: resource,
      }],
    },
  };
}

Cognito User Pool Authorisers

API Gateway validates JWT tokens issued by Amazon Cognito directly — no custom Lambda needed:

graph LR
  C1["Client"] --> Cognito["Cognito (login)"] --> JWT["JWT token"]
  C2["Client"] -->|JWT in header| API["API Gateway"] -->|Validates with Cognito| L["Lambda"]

---

Throttling and Rate Limiting

API Gateway protects your backends with built-in throttling: