System Design HLD-03.08
API gateway and backend-for-frontend
One front door for many services: routing, TLS, authentication, rate limits and aggregation, backends-for-frontends per client, and the risks of a central hop.
The big idea
Once a product is made of many services (users, orders, payments, search, notifications), clients face a mess. Which address does each service live at? Does each one check authentication its own way, enforce its own rate limits, terminate its own TLS? Does the mobile app call six services to draw one screen? An API gatewayA server that is the single entry point for client requests to many backend services, handling routing and cross-cutting concerns such as authentication and rate limiting. solves this by being the one front door. Clients talk only to the gateway; the gateway routes each request to the right service and applies the cross-cutting rules in one place.
Different clients often want different things: the mobile app wants small payloads shaped for one screen, the web app wants richer data, partners want a stable public API. A backend-for-frontendAn API layer built for one specific client type, such as the iOS app or the web app, shaping and aggregating backend data for that client's screens. (BFF) is a gateway layer dedicated to one client type, owned by the team that builds that client.
Think of a hotel reception desk. Guests do not wander the building looking for housekeeping, the kitchen and maintenance. They talk to reception, which checks who they are and routes each request to the right department.
How it works
Step 1: What a gateway does
Typical gateway features:
- Routing:
/api/orders/*goes to the orders service,/api/search/*to search, versions to the right deployment. - TLS termination and HTTP/2 or HTTP/3 to clients.
- Authentication: validate tokens or API keys once, then pass the caller's identity to services in a trusted header.
- Rate limiting and quotas per user, API key or IP, covered in Rate limiting algorithms .
- Request shaping: aggregation of several backend calls, protocol translation (public REST to internal gRPC), request and response transformation.
- Observability: one place to log, trace and measure every request.
Step 2: Backends-for-frontends
A single general-purpose gateway tends to grow into a tangle of special cases for each client. A BFF splits that: the mobile team owns the mobile BFF and shapes it exactly for their screens, without negotiating every change with the web team. The general gateway stays thin (security and routing), and BFFs hold presentation logic. GraphQL from GraphQL is a common way to implement a BFF.
Step 3: The risks
Everything goes through the gateway, so it must be treated as critical infrastructure:
- Single point of failure. Run many stateless instances behind a load balancer across zones, as in What a load balancer does .
- Extra latency. Every request takes one more hop; keep the gateway fast and avoid heavy logic in it.
- A new monolith. If business logic creeps into the gateway, every team must change it and deployments become a bottleneck. Keep it to cross-cutting concerns.
Try it
Going deeper
Gateway, load balancer, reverse proxy, service mesh
These overlap. A load balancer spreads traffic; a reverse proxy ( Reverse proxies (Nginx, Envoy, HAProxy) ) adds TLS, caching and buffering; an API gateway adds API-level concerns such as auth, keys, quotas and aggregation for traffic entering the system. A service mesh ( Service mesh ) handles similar concerns for traffic between services inside the system. Many products, such as Envoy, can play several of these roles.
Trade-offs
| Option | Wins when | Loses when |
|---|---|---|
| Single API gateway | Consistent auth, rate limits, routing and logging for all clients | Teams with very different client needs, and gateways that accumulate business logic |
| Gateway plus BFF per client | Several client types with different screens and teams owning each | More services to run, and duplicated logic between BFFs |
| No gateway (clients call services) | Very small systems with one or two services | Security, consistency and client simplicity as services multiply |
Common mistakes
- Putting business rules in the gateway, turning it into a monolith everyone must change.
- Running a single gateway instance, which takes the whole product down with it.
- Trusting identity headers from clients instead of setting them in the gateway after verification.
- Building one BFF for all clients, which recreates the general gateway's problems.
Check yourself
-
Which concern belongs in an API gateway?
Show answer
B. Authenticating requests and enforcing rate limits Cross-cutting edge concerns live in the gateway; business logic lives in services.
-
What is a backend-for-frontend?
Show answer
B. An API layer tailored to one client type, shaping and aggregating data for its screens Each client type gets an API layer built around its needs, usually owned by that client's team.
-
Why must the gateway be deployed redundantly?
Show answer
B. Every request passes through it, so one instance failing would stop everything It is on every request path, so it needs many instances behind a load balancer across zones.
-
A team keeps adding pricing rules to the gateway. What is the risk?
Show answer
B. The gateway becomes a monolith every team must change and deploy Business logic in the gateway couples all teams to one deployable and slows everyone down.
Recap
- An API gateway is the single front door for many services.
- It handles TLS, authentication, rate limits, routing, aggregation and observability once.
- Backends-for-frontends shape APIs for each client type and team.
- The gateway must be redundant and fast, since every request passes through it.
- Keep business logic in services, not in the gateway.