API gateway

Teams add an API gateway when the number of services, clients or rules grows past what each service can handle on its own. Instead of every service checking tokens, counting requests and logging calls, the gateway does it once and clients get one address.

When should you use an API gateway?

• More than a few backend services. Clients should not know which service owns which path, and services should be free to split or merge behind a stable interface.
• Several kinds of client. Web, mobile and partner integrations need different limits and formats, which is easier to manage in one place.
• Public or partner APIs. API keys, quotas, usage metering and versioning all belong at the boundary.
• Cross-cutting rules. Anything that must apply to every request is cheaper to do once.
• Breaking up a monolith. Route paths to new services one at a time.

What does an API gateway do?

• Authentication and authorization. Validate tokens or API keys, usually against an identity provider, and reject bad requests before they reach a service. See auth strategies for the options.
• Rate limiting and quotas. Count requests per client and refuse the excess, which protects services from abuse and from each other.
• Routing. Map paths and methods to services, with versioning rules such as sending /v2/orders somewhere new.
• Caching. Serve repeated read responses without calling the service.
• Transformation. Rewrite headers, translate REST to gRPC or combine several service calls into one response.
• Logging, metrics and tracing. Record every call in one place and start the trace that services continue.
• TLS termination. Decrypt once at the edge so services can use plain HTTP inside a trusted network.

How does an API gateway work?

Follow a request through the diagram at the top of this page. A web app, a mobile app and a partner system all send HTTPS requests to one gateway address. For each request the gateway runs the steps in its box: it validates the token with the identity provider, checks the caller’s rate limit, matches the path to a route and looks for a cached response. Only then does it forward the request to the orders, users, payments or inventory service.

The services never see the clients. They receive requests from one trusted caller, already authenticated, with the caller’s identity in a header. That keeps each service small, and a new client is a configuration change at the gateway rather than a change to four services.

How does an API gateway compare with a load balancer, reverse proxy and service mesh?

Component	Where it sits	What it knows	Typical job
Load balancer	In front of a pool of identical servers	Addresses and health	Spread traffic, survive a server failure
Reverse proxy	In front of one or more servers	Paths and headers	Terminate TLS, cache, hide internal addresses
API gateway	At the edge of the system	Clients, tokens, routes and limits	Authenticate, limit, route and observe every external call
Service mesh	Beside every service	Service identities and policies	Secure and observe calls between services

The gateway handles north-south traffic, which enters from outside. A service mesh handles east-west traffic between services through a sidecar proxy beside each one. Large microservices architectures often run both. In a three-tier architecture the gateway is an extra tier in front of the application servers, and in client-server terms it is the server the clients see. For more on the first two rows, see load balancing and API gateways.

What is the backend for frontend pattern?

One shared gateway can become a bottleneck: every team needs changes to it, and a response shaped for the web is wrong for a phone. The backend for frontend pattern gives each client type its own small gateway, owned by the team that owns the client. The mobile BFF combines the calls a screen needs into one response and trims the fields. Both BFFs can sit behind the shared gateway for authentication and rate limiting, or replace it when the system is small.

How do you add an API gateway?

1. Inventory the routes. List every external path, which service answers it and which clients call it.
2. Decide what moves to the gateway. Authentication, rate limiting and logging usually go first. Leave business rules in the services.
3. Choose the deployment. A managed cloud gateway, a self-hosted one such as Kong or Envoy or a BFF per client.
4. Route one path at a time. Start with a low-risk read endpoint and move the rest once it behaves.
5. Lock the services down. Once every call arrives through the gateway, services should refuse traffic from anywhere else.
6. Diagram it. Put the gateway on the system architecture diagram, or as a container on a C4 diagram, with its responsibilities listed.

What are common API gateway mistakes?

• Business logic in the gateway. A gateway that knows what an order is has become a service that every team must change.
• A single gateway for everything. One gateway owned by one team is a queue every other team waits in. Consider BFFs.
• No timeouts or circuit breakers. A slow service behind the gateway can tie up every connection and take the whole API down.
• Skipping internal security. A gateway that authenticates clients does nothing for a service calling another service. That is the mesh’s job.
• Leaving it off the architecture diagram. Rate limits and routing rules shape behavior.

What tools can you use to document an API gateway?

• OpenAPI specifications. Most gateways import routes from an OpenAPI document, which doubles as the client contract.
• Drag-and-drop diagramming tools. Fine for a one-off picture, but routes change often and the picture rarely keeps up.
• AI diagramming tools. Tools like Eraser turn a route list or a description of your services into an architecture diagram with the gateway’s responsibilities in the picture, which you can keep editing as routes move.

For more on this kind of diagram, see API diagrams.

Frequently asked questions