Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 4 · Lesson 21 · 4 min read

API Gateway and BFF Pattern for API Design

On this page
  1. The problem: many services, many clients
  2. What an API gateway does
  3. The backend-for-frontend (BFF) pattern
  4. Combining an API gateway with BFFs
  5. Trade-offs of gateways and BFFs
  6. Check yourself

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:

Code
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 omits

Each 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:

JavaScript
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):

Code
{"name":"Ana","recentOrders":[{"id":482,"status":"paid"}],"recommendations":[]} in ~300 ms

The 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.

A gateway handles cross-cutting concerns at the edge; behind it, one backend-for-frontend per client type aggregates services into the shape each client needs.
A gateway handles cross-cutting concerns at the edge; behind it, one backend-for-frontend per client type aggregates services into the shape each client needs.

Combining an API gateway with BFFs

Code
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.