Backend for Frontend: Per-Client API Aggregation Done Right

TL;DR: A Backend for Frontend (BFF) is a thin server-side aggregation service owned by one client team, serving one UI. It calls downstream microservices, reshapes their responses for that specific client, and handles perimeter concerns like auth and rate limiting. The pattern was discovered at SoundCloud during their 2011-2013 monolith decomposition and formalized in 2015 by Phil Calcado¹ and Sam Newman². The single rule that determines success or failure: the team that ships the client owns the BFF. If a platform team owns it, you have rebuilt the bottleneck the pattern was meant to eliminate.

Learning Objectives

After this module, you will be able to:

• Explain why a single public API often underserves diverse clients
• Design a BFF that aggregates microservice calls for one client type
• Compare BFF vs API gateway vs GraphQL federation and pick deliberately
• Avoid the common BFF anti-patterns (shared BFFs, business logic leakage)
• Decide team ownership: the client team owns the BFF, or it is not a BFF

Intuition

You run a travel agency. Three types of customers walk in: backpackers who want the cheapest flights and hostels on one page, business travelers who need lounge access and expense-report-friendly receipts, and corporate accounts that want a stable monthly invoice with zero surprises.

Your back office has specialists: one desk handles flights, another handles hotels, a third handles billing. If you force all three customer types to walk desk to desk collecting their own information, backpackers waste time at the lounge desk, business travelers get hostel recommendations they will never use, and corporate accounts get overwhelmed by options they cannot expense.

The fix is obvious: assign one concierge per customer type. The backpacker concierge visits the flights desk and the hostels desk, assembles a single sheet with the cheapest options, and hands it over. The business concierge visits flights, lounges, and billing, assembles an expense-ready packet. The corporate concierge visits billing and flights on a fixed monthly schedule.

Each concierge knows exactly what their customer type needs. They never ask the back-office desks to change their processes. They just visit the right desks, collect the right data, and reshape it for their customer.

That concierge is a BFF. The back-office desks are your microservices. The customer types are your clients: mobile app, web SPA, partner integration. API Design Basics introduced the primitives of REST and GraphQL. Monolith vs Microservices explained why you decompose into services. This chapter shows what sits between those services and the clients that consume them.

Theory

The problem: one API cannot serve everyone

A generic public API must be stable (partners depend on it), fine-grained (flexibility for unknown use cases), and unopinionated (no assumptions about UI layout). These constraints directly conflict with what a mobile app needs: minimal payloads, aggregated responses, and fast iteration without cross-team negotiation.

The result is two daily pains:

• Over-fetching. The mobile app calls /users/123 and receives 40 fields when it needs 3. Multiply by every endpoint on the home screen, and you are shipping kilobytes of unused JSON over a cellular connection.
• Under-fetching. The web dashboard needs data from users, orders, and inventory to render one page. Three sequential round trips, each adding network latency. At PayPal, every client-to-server round trip cost at least 700 ms at p99³. Three round trips meant 2+ seconds before the UI could render.

flowchart LR
    subgraph Problem["One API serves all clients"]
        Mobile[Mobile App] -->|"GET /users/123\n(gets 40 fields, needs 3)"| API[Generic Public API]
        Web[Web Dashboard] -->|"3 sequential calls\n(users + orders + inventory)"| API
        Partner[Partner] -->|"Stable contract\n(cannot break)"| API
    end
    API --> Users[Users Service]
    API --> Orders[Orders Service]
    API --> Inventory[Inventory Service]

The temptation is to add mobile-specific endpoints to the public API. But now every mobile UI change requires cross-team negotiation with the API team, and the public API accumulates client-specific cruft that confuses partners.

The BFF pattern: one backend per experience

A BFF is a thin server-side service with three jobs:

1. Aggregate. Fan out to downstream microservices in parallel, collect responses.
2. Reshape. Transform and prune the combined data into exactly what the client needs.
3. Enforce perimeter concerns. Authentication, rate limiting, header sanitization, CORS.

A BFF does NOT:

• Contain business logic (pricing rules, entitlements, authorization decisions)
• Hold state beyond a request-scoped cache
• Serve multiple client types

Phil Calcado’s key insight: “The BFF is part of the application”¹. It is not an API the client calls from the outside. It is the server half of the client, sharing the same team, the same release cadence, and the same on-call rotation.

flowchart LR
    iOS[iOS App] --> iOSBFF[iOS BFF]
    Android[Android App] --> AndroidBFF[Android BFF]
    Web[Web SPA] --> WebBFF[Web BFF]
    Partner[Partner] --> PartnerAPI[Partner API v2026-03]

    iOSBFF --> Catalog[Catalog Service]
    iOSBFF --> Users[Users Service]
    AndroidBFF --> Catalog
    AndroidBFF --> Users
    WebBFF --> Catalog
    WebBFF --> Users
    WebBFF --> Inventory[Inventory Service]
    PartnerAPI --> Catalog
    PartnerAPI --> Pricing[Pricing Service]

Ownership is the single most important variable. Newman and Calcado converge on this: the BFF must be owned by the team that ships the corresponding UI¹². If a platform team owns the BFF, every UI change needs cross-team coordination, which reintroduces the exact bottleneck the pattern eliminates. Stewart Gleadow’s heuristic: “one experience, one BFF”².

BFF vs API gateway vs GraphQL federation

These three patterns overlap but solve different problems. Reverse Proxies and API Gateways covered the gateway in depth. Here is how they compare:

Key distinctions:

• An API gateway sits in front of BFFs (or in front of services directly). It handles policy; it does not reshape payloads.
• GraphQL can be implemented as a BFF (PayPal did this³) or as a shared schema (which Calcado warns reproduces the “Enterprise Data Model” failure if not scoped carefully).
• Netflix’s Studio API evolved through multiple architectural phases before landing on GraphQL Federation with 70 Domain Graph Services and ~10 ms worst-case query planning overhead⁴.

flowchart TD
    subgraph GW["API Gateway Pattern"]
        direction LR
        G_Client[Any Client] --> G_GW[Gateway: auth + rate limit]
        G_GW --> G_S1[Service A]
        G_GW --> G_S2[Service B]
    end
    subgraph BFF_Pattern["BFF Pattern"]
        direction LR
        B_iOS[iOS] --> B_BFF[iOS BFF]
        B_Web[Web] --> B_BFF2[Web BFF]
        B_BFF --> B_S1[Service A]
        B_BFF2 --> B_S1
        B_BFF --> B_S2[Service B]
    end
    subgraph Fed["GraphQL Federation"]
        direction LR
        F_Client[Any Client] --> F_GW[GraphQL Gateway]
        F_GW --> F_DGS1[DGS: Movies]
        F_GW --> F_DGS2[DGS: Talent]
    end

The OAuth BFF pattern

The IETF’s “OAuth 2.0 for Browser-Based Applications” (draft-ietf-oauth-browser-based-apps-26, December 2025) names the BFF as the most secure architecture for SPAs handling OAuth⁵. The security model is simple: the browser never sees an access token.

The BFF is a confidential OAuth client. It obtains tokens via Authorization Code + PKCE, binds them to a cookie-backed session, and proxies every API call by stripping the cookie and attaching the correct access token. Cookies MUST be Secure and HttpOnly, SHOULD use SameSite=Strict, and SHOULD use the __Host- prefix.

sequenceDiagram
    participant Browser
    participant BFF
    participant AS as Authorization Server
    participant RS as Resource Server

    Browser->>BFF: GET /bff/orders (Cookie: __Host-sid)
    BFF->>BFF: Lookup session, find access token
    alt Token expired
        BFF->>AS: refresh_token grant + client credentials
        AS-->>BFF: New access token
    end
    BFF->>RS: GET /orders (Authorization: Bearer token)
    RS-->>BFF: 200 orders JSON
    BFF-->>Browser: 200 orders JSON (no token exposed)

This mitigates token theft, silent-frame token acquisition, and persistent refresh-token exfiltration. The IETF draft presents the BFF as the most secure architecture pattern for browser-based OAuth applications, listing it first among three patterns in “decreasing order of security”⁵.

Modern alternatives: when the BFF dissolves into the framework

For single-origin apps (one team, one client, one server), modern frameworks collapse the BFF into the framework itself:

• Remix loaders act as per-route BFF endpoints: hide bearer tokens, prune responses, move HTML escaping server-side.
• Next.js Server Actions let React components call server functions directly without an explicit API layer.
• tRPC provides end-to-end type-safe RPC for TypeScript monorepos with zero codegen.

These are not replacements for the BFF pattern. They are the BFF pattern dissolved into the framework for single-origin apps. For multi-client products (mobile + web + partner), you still need explicit per-client BFFs because a Remix loader cannot serve your iOS app.

Real-World Example

SoundCloud: where the BFF was born

SoundCloud’s architecture transition from a Rails monolith to microservices began in 2011. The public API, used by web, mobile, and third-party developers, became a bottleneck: every new feature had to be added without breaking any client¹.

The fix was to give each client team its own thin edge service. By 2015, SoundCloud ran approximately 5 BFFs in production: a shared iOS/Android listener BFF, web, embed/partners, the creator app Pulse, and the public-api-strangler¹². Each BFF was a Finagle-based service that accepted HTTP from one client class and fanned out to internal microservices.

The numbers tell the story. Before BFFs, rendering a user profile page required hundreds of fine-grained API calls. After introducing the BFF’s Presentation Model endpoints, that dropped to about a dozen⁶.

SoundCloud’s Core Engineering team built a shared BFF framework handling alerting, monitoring, telemetry, authentication, rate limiting, and header sanitization. This framework updated on a weekly release cadence⁷. The rule for duplication: extract shared logic to a library or service only when the same code appears in 3+ BFFs (rule of three).

A special BFF called the public-api-strangler sat in front of the old Rails monolith, proxying calls and progressively reimplementing them against new microservices. This was the mechanism for incrementally strangling the monolith without a big-bang rewrite⁷.

The retrospective lesson: SoundCloud initially shared one BFF between iOS and Android listener apps. The apps’ API needs diverged more than expected, and the team later said they would split by platform if redoing it⁷. A shared BFF is an anti-pattern even when the clients seem similar.

Trade-offs

Common Pitfalls

Exercise

Your company has a React web app, iOS and Android apps, and a public partner API. You currently expose one REST API to all four. Design the BFF layout: who owns what, how backend services change, what you move to GraphQL (if anything), and how you migrate without a big bang.

Key Takeaways

• A BFF is a thin aggregation service owned by one client team, serving one UI. It aggregates, reshapes, and enforces perimeter concerns. Nothing else.
• The team that ships the client owns the BFF. If a platform team owns it, you have rebuilt the bottleneck the pattern was meant to eliminate.
• A shared BFF is just another monolithic API. Tolerate duplication across BFFs; extract to a shared service only at the rule-of-three threshold.
• BFF, API gateway, and GraphQL federation solve different problems. Use a gateway for cross-cutting policy, a BFF for per-client shaping, and federation when 70+ services need a unified graph.
• The OAuth BFF pattern (IETF BCP draft-26) is the most secure SPA architecture: the browser never sees tokens.
• Modern frameworks (Remix, Next.js, tRPC) dissolve the BFF into the framework for single-origin apps. For multi-client products, explicit BFFs still win.
• Keep business logic out of BFFs. The BFF owns the Presentation Model, not the domain model.

Further Reading

• The Back-end for Front-end Pattern (BFF) by Phil Calcado - The origin essay from SoundCloud; the definitive narrative of how BFFs emerged from monolith decomposition pain.
• Pattern: Backends For Frontends by Sam Newman - The canonical formalization; covers team ownership, per-client vs per-user-type boundaries, and perimeter concerns.
• BFF @ SoundCloud by Lukasz Plotnicki - ThoughtWorks writeup with SoundCloud engineers; focuses on the strangler BFF and shared framework trade-offs.
• Some thoughts on GraphQL vs BFF by Phil Calcado - The 2019 follow-up distinguishing BFF (ownership pattern) from GraphQL (wire protocol); essential for the comparison table.
• How Netflix Scales its API with GraphQL Federation - Netflix Studio Edge: the BFF-to-federation journey with 70 Domain Graph Services.
• GraphQL: A Success Story for PayPal Checkout - Mark Stuart’s case study; the 700 ms round-trip number and the REST-to-Batch-to-GraphQL journey.
• OAuth 2.0 for Browser-Based Applications (draft-26) - The IETF BCP naming BFF as the most secure SPA OAuth pattern; read Section 6.1 for cookie requirements.
• Pact: Consumer-Driven Contract Testing - The standard tool for catching client-BFF contract drift without shared staging environments.

Flashcards

References