API Gateway Patterns for Microservices

An API gateway sits between clients and your services. At minimum, it routes requests. At its best, it handles cross-cutting concerns (auth, rate limiting, observability) so your services don't have to. At its worst, it becomes a monolithic bottleneck that every team fights over.

What Belongs in the Gateway

The gateway should handle concerns that apply uniformly across services:

• Routing: Map external URLs to internal services
• Authentication: Validate tokens, reject unauthenticated requests
• Rate limiting: Protect services from abuse
• TLS termination: Handle HTTPS at the edge
• Request/response transformation: Add headers, strip internal headers
• Observability: Access logs, request metrics, trace propagation

The gateway should NOT handle:

• Authorization: "Can user X do action Y?" depends on business context. Keep this in services.
• Business logic: Request validation, data transformation, orchestration — these belong in services or BFF layers.
• Data aggregation: Fetching from multiple services and combining results (unless you're using the BFF pattern explicitly).

Pattern 1: Simple Reverse Proxy

Route requests to the right service based on URL path. This is the starting point.

Kong configuration:

Envoy configuration:

Pattern 2: Authentication Offloading

Validate JWTs at the gateway. Services receive pre-validated identity information in headers — they never see the raw token.

Trust boundary: Services behind the gateway trust the X-User-ID header. This means the gateway must be the only entry point — if services are directly accessible, anyone can forge headers. Enforce network policies that prevent direct access to services from outside the cluster.

Pattern 3: Backend for Frontend (BFF)

Different clients (web, mobile, IoT) have different data needs. Instead of one generic API, create a thin backend per frontend that aggregates and shapes data.

The BFF aggregates multiple service calls into a single response shaped for the specific client:

The mobile BFF would return the same data but with smaller image URLs, fewer fields, and different pagination defaults.

Trade-off: BFFs prevent the "one API serves all clients" compromise but introduce code duplication across BFFs. Keep BFFs thin — they should only aggregate and transform, not contain business logic.

Pattern 4: Circuit Breaking at the Gateway

When a backend service is failing, the gateway can stop forwarding requests to it (circuit open), preventing cascading failures and reducing latency for error responses.

Envoy circuit breaker configuration:

This ejects a host from the load balancing pool after 5 consecutive 5xx errors. After 30 seconds, it's allowed back in on a trial basis.

Pattern 5: Canary Routing

Route a percentage of traffic to a new version of a service. The gateway makes traffic splitting decisions based on headers, weights, or user segments.

Comparing Gateway Options

My recommendation:

• Kong if you want a batteries-included API gateway with a plugin marketplace and admin UI. Good for teams that want configuration over code.
• Envoy if you need raw performance, are already using Kubernetes, or plan to adopt a service mesh. Steeper learning curve but more powerful.
• AWS API Gateway if you're all-in on AWS and want zero infrastructure management. Limited customization but zero ops.

Anti-Patterns

The god gateway. Putting business logic, data transformations, and orchestration in the gateway. It becomes a monolith that every team depends on and nobody owns.

Gateway per team. Each team deploys their own gateway with different configurations. You end up with inconsistent auth, logging, and rate limiting across the platform.

No gateway at all. Every service handles its own TLS, auth, rate limiting, and CORS. Inconsistencies multiply, and changing auth strategy requires modifying every service.

The sweet spot: one gateway (or one per environment) that handles cross-cutting concerns consistently, with services handling their own business logic and authorization. Keep the gateway thin, keep it consistent, and resist the temptation to put business logic in it.