API Gateway

An API Gateway is like a front door for your backend services. It handles all requests from clients (like web or mobile apps) and forwards them to your serverless functions or other services.

🧩 Main Roles of an API Gateway

1. Request routing 🚦

• Receives client requests (HTTP, WebSocket, etc.)

• Sends them to the correct backend (Lambda, EC2, S3, etc.)

1. Security & Authentication 🔐

• Can check tokens, API keys, or integrate with Cognito for login

• Blocks unauthorized requests

1. Rate limiting & throttling ⏱️

• Controls how many requests a client can make in a time frame

• Prevents backend overload

1. Data transformation 🔄

• Can convert request/response formats (e.g., JSON → XML)

• Makes backend simpler by standardizing input/output

1. Monitoring & Logging 📊

• Tracks traffic, errors, and performance metrics

✅ Real-world Example

Imagine an online shoe shop app:

1. User clicks “Place Order” in the app

2. API Gateway receives the request

3. It checks if the user is logged in (Cognito authentication)

4. Routes request to Lambda function that processes the order

5. Returns the result back to the app

📖 Analogy

• API Gateway = Receptionist of an office building

  • Checks who you are (authentication)

  • Directs you to the right department (routing)

  • Limits entry if too many people come at once (throttling)

  • Logs all visits (monitoring)

🔑 AWS

• Amazon API Gateway (HTTP, REST, WebSocket)

• Integrates perfectly with Lambda, Step Functions, S3, DynamoDB, etc.

Three Phases of API Gateway

When a request comes to an API Gateway, it goes through three main phases:

Client Request Phase (Incoming Request)

• The client (web, mobile app, or service) sends a request to the API Gateway.

• API Gateway receives the request and starts processing.

• Checks HTTP method, URL, headers, and authentication.

⚡ Example:

• User clicks “Place Order” → sends POST request to /order endpoint.

• API Gateway receives the request.

Processing Phase (Gateway Logic & Routing)

• API Gateway does the heavy lifting before sending it to the backend:

  1. Authentication / Authorization → checks if the request is allowed (e.g., via Cognito, API Key, JWT token).

  2. Validation → checks if request parameters are correct.

  3. Transformation / Mapping → changes request format if needed (JSON → XML).

  4. Routing → forwards request to the correct backend service (Lambda, S3, Step Functions, etc.).

⚡ Example:

• Request is validated → routed to Lambda function that processes the order.

Response Phase (Return to Client)

• The backend sends a response back to API Gateway.

• API Gateway can transform the response if needed, add headers, or handle errors.

• Sends the final response back to the client.

⚡ Example:

• Lambda returns { "status": "Order Placed", "orderId": 123 }

• API Gateway sends this to the app, which shows a confirmation to the user.

📖 Analogy

Think of API Gateway like a restaurant receptionist:

1. Client Request = customer arrives at the reception.

2. Processing = receptionist checks the reservation, asks questions, and sends the order to the kitchen.

3. Response = the kitchen prepares food, receptionist hands it back to the customer.

API Gateway Authentication

Authorization in API Gateway controls who can access your API and what they are allowed to do.

It usually happens after authentication (verifying identity).

Types of Authorization in API Gateway

IAM Roles & Policies (AWS Managed)

• Uses AWS credentials to allow/deny access.

• Typically for internal AWS clients (Lambda, EC2, another API).

• Example:

  • Only Lambda function with the correct IAM role can call your API.

Cognito User Pools

• Uses Amazon Cognito to manage users and tokens.

• API Gateway validates JWT tokens from Cognito.

• Example:

  • Users log in via your app → Cognito issues token → API Gateway allows access only if token is valid.

Lambda Authorizer (Custom Authorizer)

• A custom Lambda function decides whether a request is allowed.

• Can use any logic or external system (database, OAuth, third-party token).

• Example:

  • Check if user subscription level allows access to premium API features.

Resource Policies

• Lets you allow or deny access based on IP address, VPC, or AWS account.

• Example:

  • Only allow requests from your corporate network or a specific VPC endpoint.

⚡ How it works (Flow)

1. Client sends request to API Gateway.

2. API Gateway checks authorization (IAM, Cognito, Lambda authorizer, or resource policy).

3. If authorized → request goes to backend (Lambda, S3, etc.).

4. If unauthorized → API Gateway returns 403 Forbidden.

📖 Analogy

• Authentication = “Who are you?” (ID check at the door)

• Authorization = “What can you do?” (VIP lounge, restricted areas, or full access)

✅ Key point:

• Authorization ensures only allowed users or systems can access your APIs, protecting your backend.

API Gateway Enpoint types

AWS API Gateway supports three main types of endpoints, which determine how your API is accessed:

Edge-Optimized Endpoint 🌍

• Designed for: Global clients

• How it works:

  • Requests go through CloudFront (AWS global CDN).

  • Fast access for users anywhere in the world.

• Use case: Public APIs accessed globally.

• Analogy: International airport → routes passengers (requests) efficiently from anywhere.

Regional Endpoint 🏙️

• Designed for: Clients in the same region as your API.

• How it works:

  • Requests go directly to the API Gateway in the same region.

  • Slightly faster for local users, cheaper than edge-optimized.

• Use case: Internal apps, enterprise APIs, or regional traffic.

• Analogy: Local bus station → serves nearby passengers quickly.

Private Endpoint 🔒

• Designed for: VPC-only access (private network).

• How it works:

  • API is not exposed publicly.

  • Only accessible from inside your VPC using VPC endpoints.

• Use case: Internal microservices, sensitive data APIs.

• Analogy: VIP-only entrance → only authorized people inside.

Endpoint Type	Access	Use Case
Edge-Optimized	Global (via CloudFront)	Public API for worldwide users
Regional	Regional (direct)	Local or regional clients
Private	VPC only	Internal/private APIs

API Gateway Stages

A stage in API Gateway is like a versioned environment of your API. It’s where your API is deployed and made accessible to clients

🧩 Key Concepts

1. Stages are Environments 🌱

• Each stage represents a different deployment environment:

  • dev → for testing

  • test → for QA

  • prod → for real users

1. Stage Variables ⚙️

• Variables specific to a stage that your API or Lambda can use.

• Example:

  • db_table_name = “OrdersDev” for dev stage, “OrdersProd” for prod stage

1. Endpoint URLs 🌐

• Each stage gets a unique URL:

  • Example:

    • Dev: https://abcd1234.execute-api.us-east-1.amazonaws.com/dev

    • Prod: https://abcd1234.execute-api.us-east-1.amazonaws.com/prod

1. Deployment 🚀

• You deploy your API to a stage after making changes.

• Old stage versions remain intact until updated.

1. Monitoring & Throttling per Stage 📊

• You can set logging, metrics, and throttling limits for each stage separately.

API Gateway Errors

When a client calls your API, sometimes things go wrong. API Gateway classifies errors mainly by HTTP status codes and types.

Client-Side Errors (4XX)

• Meaning: The request from the client was wrong or unauthorized.

• Common Status Codes:

  • 400 Bad Request → Invalid input or malformed request

  • 401 Unauthorized → No authentication token or invalid token

  • 403 Forbidden → Authenticated but not allowed to access resource

  • 404 Not Found → API or resource does not exist

  • 429 Too Many Requests → Throttling limit exceeded

⚡ Example:

• User sends an order with missing fields → 400 Bad Request

• User tries to access an admin API without proper role → 403 Forbidden

Server-Side Errors (5XX)

• Meaning: Something went wrong on the backend or API Gateway itself.

• Common Status Codes:

  • 500 Internal Server Error → Backend function (Lambda) failed

  • 502 Bad Gateway → API Gateway couldn’t reach backend properly

  • 503 Service Unavailable → Backend is overloaded or unavailable

  • 504 Gateway Timeout → Backend took too long to respond

⚡ Example:

• Lambda crashes while processing an order → 500 Internal Server Error

• S3 service is temporarily down → 503 Service Unavailable

Mapping & Custom Errors

• API Gateway can map backend errors to custom messages.

• Example:

  • Lambda returns an error → API Gateway maps it to a friendly JSON:

  • { "error": "Unable to process order", "code": 500 }

📖 Analogy

• 4XX (Client) = Customer filled the order form wrong → issue is with them

• 5XX (Server) = Kitchen made a mistake or oven broke → issue is internal

https://docs.aws.amazon.com/apigateway/latest/api/CommonErrors.html

API Gateway Caching

API Gateway caching stores the response of your API for a period of time so that repeated requests don’t have to hit the backend every time.

🧩 How it works

1. A client requests data (e.g., product list).

2. API Gateway forwards the request to backend (Lambda, S3, etc.) the first time.

3. API Gateway stores the response in cache for a defined TTL (Time-To-Live).

4. Next time the same request comes in, API Gateway returns the cached response immediately — no backend call needed.

✅ Benefits

1. Faster responses 🚀 → reduces latency.

2. Reduces load on backend 🛡️ → saves compute and cost.

3. Scales better 📈 → handles more users with less stress on servers.

⚡ Example

• Your online shoe shop app asks: “Show all shoes in stock”

• First request → hits Lambda → gets 100 shoes → API Gateway caches it.

• Next 50 users request the same → API Gateway serves cached data instantly instead of calling Lambda each time.

🔧 Key Configurations

• Cache TTL → how long the data stays in cache (seconds, minutes, hours).

• Cache key → determines which requests are cached (usually based on URL + query params + headers).

• Invalidate / Flush → you can manually clear the cache if data changes.

📖 Analogy

API Gateway cache is like a fast-food restaurant pre-prepping popular items:

• First customer orders → chef makes it fresh.

• Next customers get the already-prepared food immediately → faster service, less chef work.