API Gateways, simply explained

Reading time: ~6 minutes

What is an API Gateway?

An API Gateway is a service that sits in front of your back-end services and acts as a single entry point for client requests. It receives an HTTP (or gRPC) request, applies cross-cutting rules (authentication, rate limits, caching, routing), and forwards the request to the right downstream service. It then collects the response, adds or removes headers if needed, and returns it to the client.

Think of it as the front door to your APIs. Instead of exposing each service directly to the outside world, you put the gateway in front so common work happens once, in one place.

Why use one?

Single endpoint for clients: Mobile/web apps don’t need to know where each service lives.
Cross-cutting policies: Auth, TLS termination, quotas, caching, request/response transformation.
Decoupling: You can evolve internal services or change their URLs without breaking external clients.
Observability: Central point for metrics, logs, and tracing headers.

What it is not

Not a business-logic layer. Keep it thin; complex orchestration belongs in services or a dedicated “backend-for-frontend” (BFF).

Gateway for shared concerns, BFF for UI-specific composition

Not a silver bullet for performance: It adds a hop; use caching and keep filters light.
Not the same as a service mesh: Meshes mainly solve service-to-service traffic; gateways focus on edge traffic.

Common features (pick what you need)

Routing: Path and method based (/orders/* → orders-service).
Authentication & authorization: JWT, OAuth 2.0 introspection, API keys.
Rate limiting & quotas: Per key, per IP, or per user.
Caching: Short-lived edge cache for GETs.
Request/response transformation: Header/body mapping, version negotiation.
Aggregation (optional): Gateway composes responses from several services (use sparingly).
Observability: Access logs, structured metrics, distributed tracing headers (e.g., traceparent).
Resilience: Timeouts, retries, circuit breakers.

A small example

Client → Gateway → Services

GET /v1/orders/123

Gateway rules:
- Check JWT (must have scope: orders:read).
- Apply rate limit: 60 req/min per API key.
- Route: /v1/orders/* → http://orders:8080
- Forward tracing headers.
- Cache GETs for 10s.

If the orders service moves to another host or version, only the gateway config changes; clients keep calling the same URL.

When to use an API Gateway

You have multiple services or plan to split a monolith soon.
You need uniform auth and quotas across teams.
You want one domain for all client apps and partners.

Maybe skip it if you have a single service, simple needs, and you control both client and server. You can always add a gateway later.

Pitfalls to avoid

Too much logic in the gateway. Keep transformations simple.
Hidden tight coupling. Document contracts; version your routes.
Unbounded retries. Set timeouts and backoff to avoid storms.
Ignoring observability. Emit metrics from day one (latency, error rate, cache hit).