API Gateway and BFF Pattern for API Design
On this page
The problem: many services, many clients
Behind a modern product sit dozens of services: users, orders, inventory, payments, recommendations. In front sit a web app, iOS and Android apps, and partner integrations. Letting every client call every service directly means each client handles authentication, retries and data assembly, and every service is exposed to the internet.
What an API gateway does
An API gateway is one entry point that handles cross-cutting concerns for all services. Picture the reception desk of an office building: it checks badges, signs visitors in and points them to the right floor, but it doesn't do anyone's actual job. "Cross-cutting" means needed by every service, so it's done once at the door:
- Routing by path or host to the right service.
- Authentication (validating tokens or API keys) and coarse authorization.
- Rate limiting and quotas per client (Day 11).
- TLS termination, request size limits, CORS, request IDs.
- Observability: consistent access logs, metrics and traces.
Examples: AWS API Gateway, Kong, Apigee, Azure API Management, Envoy-based gateways, nginx (see the networking course).
What doesn't belong in a gateway: business logic. Gateways that accumulate custom transformations and orchestration become a bottleneck every team must change and a single point of failure for every product decision.
The backend-for-frontend (BFF) pattern
Different clients need different things. The mobile app wants small payloads and fewer calls; the web dashboard wants richer data; partners want a stable, documented API. A single shared response shape serves none of them well.
A backend-for-frontend (a pattern described by Sam Newman, used at SoundCloud) is a thin backend per client type, usually owned by that client's team:
Single shared endpoint
GET /api/dashboard -> the same aggregated shape for web and mobile
Backend-for-frontend
GET /mobile-bff/dashboard -> trimmed fields, smaller images, one combined call
GET /web-bff/dashboard -> richer fields, includes data mobile omitsEach BFF calls the underlying services, aggregates their data, and shapes it for its client. The mobile team can change its BFF on its own release schedule.
Here's the core of a mobile BFF endpoint. It calls three services in parallel, gives each a deadline, and treats recommendations as optional:
const withTimeout = (promise, ms) =>
Promise.race([promise, sleep(ms).then(() => { throw new Error('timeout'); })]);
async function mobileDashboard(userId) {
const [profile, orders, recs] = await Promise.allSettled([
withTimeout(profileService.get(userId), 500),
withTimeout(orderService.recent(userId), 500),
withTimeout(recommendationService.forUser(userId), 300),
]);
if (profile.status === 'rejected' || orders.status === 'rejected')
throw new Error('required data missing'); // becomes a 503
return {
name: profile.value.name,
recentOrders: orders.value.slice(0, 3), // mobile shows three
recommendations: recs.status === 'fulfilled' ? recs.value : [],
};
}Tested with fake services taking 80 ms, 120 ms and 3 seconds (recommendations having a bad day):
{"name":"Ana","recentOrders":[{"id":482,"status":"paid"}],"recommendations":[]} in ~300 msThe screen still loads in 300 ms instead of waiting 3 seconds, just without recommendations. Called one after another, the same three calls would take the sum of their times, not the slowest one.
Combining an API gateway with BFFs
Clients ── API gateway ──┬── Web BFF ─────┐
(web, mobile, partners) ├── Mobile BFF ──┼── users, orders, inventory, payments services
└── Public REST API (partners)- The gateway handles auth, rate limits, TLS and routing for everything.
- BFFs handle aggregation and shaping for first-party clients.
- Partners get a stable, versioned public API.
A GraphQL server often plays the BFF role: one schema per client population, or one shared graph where each client selects what it needs (Day 20).
Trade-offs of gateways and BFFs
- More components to run. Each BFF is a service with deployment, monitoring and on-call.
- Duplication between BFFs. Some logic gets repeated; push logic that every client needs down into services, not into a shared BFF that grows into a monolith.
- Latency: each hop adds a little. BFFs should call services in parallel and keep timeouts tight (see the distributed systems course on cascading failures).
- Ownership matters: a BFF works best when the client team owns it; a BFF owned by a separate backend team recreates the coordination problem.
Check yourself
Cross-cutting concerns like routing, authentication, rate limiting, TLS termination and request logging belong there. Business logic and orchestration across services don't; they turn the gateway into a shared bottleneck every team must change.
It can return small, mobile-shaped payloads in fewer calls, and the mobile team can change it on their own schedule.
It accumulates every client's special cases and becomes a bloated, shared bottleneck that all teams must coordinate on, the very problem BFFs were meant to avoid. One BFF per client experience keeps each small.
Call them in parallel, so the total is about the slowest call (300 ms) instead of the sum (500 ms), and give optional calls a timeout with a fallback.