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

Need API keys / usage plans?         ---> REST API
Need request/response validation?    ---> REST API
Need caching?                        ---> REST API
Need WAF integration?                ---> REST API
Need private API endpoints?          ---> REST API
Need lowest cost + simple proxy?     ---> HTTP API
Need JWT authorisation (built-in)?   ---> HTTP API
Need fastest latency?                ---> HTTP API
Need 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):

/                          (root)
├── /users                 GET    -> List users
│   ├── /{userId}          GET    -> Get user by ID
│   │                      PUT    -> Update user
│   │                      DELETE -> Delete user
│   └── /{userId}/orders   GET    -> List user's orders
├── /orders                POST   -> Create order
│   └── /{orderId}         GET    -> Get order by ID
└── /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

Client                    API Gateway                      Backend
  |                          |                               |
  |--- HTTP Request -------->|                               |
  |                          |-- Authentication ------------>|
  |                          |-- Request Validation -------->|
  |                          |-- Request Transformation ---->|
  |                          |--- Invoke Backend ----------->|
  |                          |                               |
  |                          |<-- Backend Response ----------|
  |                          |-- Response Transformation --->|
  |                          |-- Caching (if enabled) ------>|
  |<-- 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:

Client ---> Cognito (login) ---> JWT token
Client ---> API Gateway (JWT in header) ---> Validates with Cognito ---> Lambda

---

Throttling and Rate Limiting

API Gateway protects your backends with built-in throttling: