API Gateway

An API gateway is the shared entry point for north-south traffic, handling routing, authentication, rate limits, and response aggregation before requests reach services.

architecture

Definition

An API gateway sits between external clients and internal services. It terminates TLS, authenticates callers, applies rate limits, routes requests to the right service, and may aggregate responses. It centralizes concerns that would otherwise be duplicated in every service, but it must not become a second business-logic layer.

Context and scope

Gateways are used when many clients call many services, when authentication and quotas must be enforced consistently, or when public API shape differs from internal service boundaries.

Common misconceptions

A gateway is only a reverse proxy — routing is the minimum; auth, quotas, and observability are the value
The gateway should own business rules — domain logic in the gateway becomes a distributed monolith
A gateway removes the need for service-level authorization — every service must still enforce its own rules

Anti-patterns

Putting database queries or orchestration logic in the gateway
Terminating TLS at the gateway and then using plaintext across an untrusted network
Applying one global timeout that ignores the latency of each route

Related concepts

Related examples

typescript/sliding-window-rate-limiter

Authoritative source

https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway

One edge, many services

External clients should not need to know the internal service topology. A gateway exposes stable routes, authenticates the caller once, applies quotas, and forwards to the current backend. When a service moves or splits, the public contract stays stable.

routes:
  - path: /api/orders
    service: orders
    auth: bearer
    rate_limit: orders_default
    timeout: 3s
  - path: /api/catalog
    service: catalog
    auth: api_key
    cache: 60s

The configuration is illustrative; the important part is that edge policy is explicit and reviewed. A gateway that silently retries non-idempotent writes, or applies a 30-second timeout to a fast endpoint, creates production incidents of its own.

Keep domain logic out

It is tempting to enrich, validate, and orchestrate responses in the gateway because it sees every request. That couples the edge to domain rules and makes every change a gateway release. Keep business validation in the service that owns the data. The gateway should enforce identity, coarse quotas, transport security, routing, and observability.

A gateway is also a single point of failure and a shared bottleneck. Deploy it with redundancy, capacity headroom, and a tested bypass or failover path. Monitor its latency separately from backend latency; a gateway p99 problem is not a service problem but has the same user impact.

When to use it

Use an API gateway when multiple clients need a consistent edge policy or when internal topology changes frequently. The advantage is centralized auth, quotas, and routing; the drawback is an extra hop, a critical shared dependency, and the temptation to centralize too much. Compared to embedding a reverse proxy in each service, a gateway gives one control point but concentrates risk.