API Gateways and Backend-for-Frontend

Twenty services, each doing its own TLS, its own token validation, its own rate limiting — with twenty implementations, twenty bug surfaces, and one team that fixed theirs properly. The gateway exists to do those things once, for everyone: terminate TLS, validate tokens, apply quotas, route to the right backend, and log uniformly.

The dividing rule is worth memorizing: the gateway enforces policy that is identical across every API; anything that changes when the business changes belongs in a service. Authorization decisions, pricing rules, and workflow steps in the gateway create a tier owned by nobody, deployable by everybody, and untestable without the whole system up. It becomes the place where every product request queues behind a platform release.

Placement also decides failure semantics. A gateway is a single failure domain in front of all your services, so it must be stateless, multi-AZ, and scaled well beyond current load, with configuration pushed from a control plane rather than edited on instances. Health checks, graceful connection draining, and rolling restarts are not optional extras — every client's outage is now your outage. When someone asks what happens if the gateway goes down, the honest answer covers redundant instances behind a load balancer (this is why its own scaling matters), clients that back off rather than hammer, and the DNS or anycast failover path.

Do not confuse edge with origin: caching product pages or serving stale reads during a dependency outage is a graceful-degradation concern applied at the edge, not a reason to move logic there. And keep per-client shaping out of the shared gateway tier — the mobile payload problem has its own pattern, next: when one universal API stops serving every client, teams split the edge per client type rather than growing a switchyard of conditional parameters. The mechanism itself picks up from GraphQL Trade-offs, where one client-shaped endpoint already showed the pull toward per-client APIs.

Implementation choices are worth naming: managed offerings (AWS API Gateway, Google Apigee), reverse proxies with plugin ecosystems (Kong, APISIX, NGINX with Lua, Envoy), or a library-level edge when you only need routing. They differ in latency, plugin model, and how configuration reaches instances — all of which matter, because a gateway adding 30 ms to every call taxes your entire p99. Measure the edge: it sits on the hot path of every request, so its own performance is architecture, not plumbing.

The authentication boundary also needs a precise contract with services. The gateway verifies signature and expiry, then passes standardized claims downstream as trusted headers or an internal token, and services treat those claims as authoritative. If any service also accepts the raw client token, you now have two validation paths drifting apart — the gateway checks expiry, the service forgets — and you end up debugging what looks like clock skew during an outage.

The mobile home screen needs profile, notifications, and three featured items. Against the shared API it fires three requests: 600 ms of sequential round trips on a 200 ms link, downloading forty fields to render five. The web app copes — more bandwidth, a team that aggregates client-side — and the partner integration wants entirely different, coarser operations. One universal API now serves all three, and it shows: ?fields=, ?include=, and ?view=mobile accumulate until nobody can name every combination that must keep working.

The backend-for-frontend pattern answers with one tailored API per client type: a mobile BFF, a web BFF, a partner API. Each composes the domain services into exactly the shape one client renders.

The discipline is in the boundaries. A BFF composes and shapes — it fans out to services, merges results, trims fields, sets response headers for its client — but it must not own domain logic: no pricing rules, no inventory decisions, nothing whose correctness the next client also depends on. Cross that line and you have built a distributed monolith with a friendly name. Size it by client type, never by client instance: a BFF per user or per feature is the trap that produces dozens of unmaintainable edge services. Two or three BFFs with clear owning teams is the healthy shape.

How this interacts with the query-shaped flexibility from GraphQL Trade-offs is a real design decision, not a rivalry: a BFF can expose a GraphQL schema tailored to its client, or serve plain JSON endpoints that already match the screen. Pick one mechanism per client — teams that adopt GraphQL and a hand-built composition layer and a gateway transformation for the same flow end up maintaining three contracts for one screen.

Two practical rules keep BFFs cheap. First, keep them thin: stateless services with straightforward HTTP calls to the domain tier, so they scale like the stateless tier of Vertical vs Horizontal Scaling. Second, version nothing inside them if you can avoid it — a BFF ships with its client, so it can change in lockstep with the app release that consumes it; that co-release ability is the pattern's entire economic argument. The API versioning burden stays on the stable domain contracts instead.

Ownership decides whether the pattern survives: the team that ships the mobile app should own the mobile BFF, because the API shape changes when their screen does, and waiting on a platform backlog defeats the purpose. That requires domain teams to treat each BFF as a first-class consumer with stable contracts and clear SLAs — otherwise every BFF starts reading databases directly, and three edge services now hold private data-access paths nobody governs.

Watch for the duplication signal: the same aggregation appearing in two BFFs means either the domain service should offer it, or one client genuinely needs it. Extracting fan-out into the service tier keeps BFFs thin; leaving it duplicated is how BFFs quietly become the new monolith you split out to avoid. Since a BFF's job is transformation, test it accordingly — snapshot the composed response for each client screen and fail CI when a domain change alters one, so the client team sees the impact in their pipeline instead of in an app-store review.

Inventory starts answering in 5 seconds instead of 50 ms. Without edge controls the cascade is mechanical: gateway threads pile up waiting, capacity for healthy routes drains alongside the sick one, clients time out and retry — multiplying load on the very service that is struggling — and within minutes the whole site is down because of one slow dependency. Everything below exists to break that chain.

Timeouts must shrink as the call travels deeper. A workable ladder: client 10 s, gateway route 8 s, service 5 s, database query 2 s. Each layer therefore fails with a real error while the layer below can still respond, instead of the outermost layer giving up on a call that is still consuming resources. Propagate the deadline (and a request id) across hops so the innermost service can stop working on a request nobody will collect.

Retries at the edge need a budget. Only idempotent methods, only on connection failures and 503, capped at one or two attempts with jitter — plus a retry budget that refuses retries beyond a small percentage of live traffic. Without the budget, a gateway retry policy converts a 10% backend failure into a 20% surge exactly when the backend is weakest. The idempotency requirement is the same rule you met in REST Design and Versioning; the edge is where violating it hurts most.

Outlier ejection is the circuit breaker's edge form. Track consecutive 5xx or a sliding success rate per upstream instance; when it trips, eject the instance from the load-balancing pool for a cool-down, fail fast with 503 and Retry-After, and probe gradually as it recovers. One broken pod stops receiving traffic without a human in the loop.

Add the last two layers deliberately: circuit breaking and rate limiting at the gateway contain downstream failures instead of importing them, and request queuing should be bounded — reject early rather than accept work you cannot finish. Then instrument per-route, per-upstream golden signals (latency, traffic, errors, saturation), because a gateway without per-upstream visibility is just a very expensive single point of failure.

Finally, design the degradation path: when inventory is open but slow, the edge can serve a cached product page and mark availability unknown rather than fail the whole request. That is the same containment philosophy one phase onward — degrade the optional, protect the core path — which is precisely what Timeouts and Retries formalizes next.

Rehearse the failure modes before they rehearse you. An open circuit must return 503 with Retry-After — a contract your client SDK has to honor, or the fast failure merely shifts the load pattern. Ejection needs hysteresis and cool-downs, or half the fleet bounces during one transient blip. And rejection must always arrive with telemetry: per-upstream error budgets let the alert fire while there is still capacity to absorb it.

Deploys are their own failure mode. A gateway that resets connections on rollout converts a routine release into a burst of client errors; graceful shutdown plus slow endpoint removal from DNS costs an afternoon and removes the most common self-inflicted outage at the edge. Drain in-flight requests, watch the connection count reach zero, then exit.