What is the difference between API composition and the backend for frontend pattern?
API composition is a query pattern. One component, the composer, receives a request, calls several services that each own part of the data, and joins the results in memory before responding. An order-detail view might pull the order from the order service, line items from catalog, and shipment status from fulfillment, then merge them by ID. Nothing about the pattern says where the composer runs or who maintains it.
The backend for frontend pattern is about exactly those two things. A BFF is a backend deployed per client experience, such as web, iOS, or a partner portal, and owned by the team that builds that client. Internally, most BFFs perform API composition. That is why "BFF or API composition?" is a category error: one is a technique, the other is an ownership boundary. The useful question is who owns the screen-shaped aggregation logic, and where its timeout, fallback, and partial-response decisions live. Those decisions encode product judgment, such as whether the page can render without shipment status. Whoever owns them needs to understand the screen.
Wherever the composer runs, it has the same limits. Its joins happen in memory, outside any transaction. Each service answers at a slightly different moment, so an aggregated view can show a refund that the payment service has recorded next to an order status that hasn't caught up yet. Joins over large result sets are also costly. Fetching thousands of rows from two services to intersect them inflates memory use and drives latency toward the slowest call.
BFF vs gateway: where should screen-specific aggregation live?
A gateway and a BFF both sit between clients and services, but they answer different questions. The gateway handles what every request needs regardless of who sent it: TLS termination, routing, authentication, rate limiting. A BFF handles what one client needs: which fields the iOS order screen shows, how the web dashboard paginates, which downstream calls a given view fans out to.
[Web app] [iOS app] [Android app]
\ | /
+------- API Gateway -------+
| TLS, auth, rate limits, |
| routing |
+---------------------------+
| | |
[Web BFF] [iOS BFF] [Android BFF]
\ | /
[Orders] [Payments] [Shipping] [Catalog]
Teams often skip the BFF tier and put screen aggregation directly into the gateway. This turns the gateway into a coupled monolith:
- Every frontend change becomes a gateway deployment. Renaming a field on one mobile screen means releasing the component that fronts all traffic.
- Every team works in one codebase. Web, iOS and Android teams queue behind each other's reviews and release windows.
- Failures spread across clients. A slow fan-out or an unhandled exception in one route's aggregation logic consumes threads, memory or connection pool slots that every other route shares.
There is one legitimate exception. If you have a single client and a handful of screens, gateway aggregation is acceptable. One team owns it, and there is no second consumer to couple to. Revisit the decision when a second client appears.
+-----------+ +-----------+ +---------------+
| Web app | | iOS app | | Android app |
+-----+-----+ +-----+-----+ +-------+-------+
| | |
v v v
+---------------------------------------------------------+
| API Gateway (shared) |
| TLS termination, authentication, rate limiting, |
| routing -- cross-cutting, identical for every client |
+-----+--------------------+----------------------+-------+
| | |
v v v
+-----------+ +-----------+ +---------------+
| Web BFF | | iOS BFF | | Android BFF |
| shaping | | shaping | | shaping |
| web team | | iOS team | | Android team |
+-----+-----+ +-----+-----+ +-------+-------+
| | |
+-+------------+-------+-------+--------------+-+
v v v v
+--------+ +----------+ +----------+ +---------+
| Orders | | Payments | | Shipping | | Catalog |
+--------+ +----------+ +----------+ +---------+
A single shared gateway applies edge concerns to all traffic, while each client team owns a separate BFF that shapes and aggregates downstream service calls for its own screens.
How do the alternatives compare for an order-detail screen?
Take an order-detail screen that shows the order, the customer's name and loyalty tier, shipment tracking, and a strip of recommended products. Four backend services own that data. The three approaches differ in which side of the network makes those four calls.
| Dimension | Client-side fan-out | Shared composition service | Per-client BFF |
|---|---|---|---|
| Round trips from device | Four, plus any calls that depend on earlier results | One | One |
| Payload shape | Four full domain responses, trimmed on the device | One generic superset that every client accepts | Only the fields this screen renders |
| Topology exposed | Every service endpoint and its auth model | One endpoint | One endpoint |
| When the screen changes | App release, plus possibly a change to each service | Composition team changes the service; every client must tolerate the change | The client team changes its own BFF |
Client-side fan-out is the easiest to build because no new service exists. The cost appears later. Each extra round trip over a mobile connection adds full radio and TLS latency. The app also hard-codes four service contracts, and it runs on devices you cannot update right away, so older app versions in the field keep those contracts in use long after you want to retire them.
Team coordination is where the options differ most. Fan-out ties client releases to every service team's versioning policy. A shared composition service turns its owning team into a queue that every client team waits in. A BFF keeps screen changes inside one team, but each client then pays for running its own service.
How does data aggregation work inside a composer?
A composer is a small dependency graph executed per request. Calls with no data dependency run concurrently: for an order-detail screen, the order, the customer profile and the loyalty balance can all start at once, so the wall-clock cost is the slowest of them, not the sum. Calls that need an earlier result have to wait. The shipment lookup needs the order ID, and the product lookups need the line items, so those form a sequential chain. Draw that graph explicitly, because the longest path through it sets your latency floor.
Give the whole request one deadline, then derive each call's timeout from the time remaining. If the screen has 800 ms and the order fetch took 300 ms, the shipment call gets what is left minus a margin for rendering, not a fixed 500 ms. A single abort signal tied to that deadline cancels every in-flight call when time runs out.
Line items are where N+1 appears. Rendering twenty items with twenty product calls multiplies latency risk and downstream load. Collect the product IDs, deduplicate them, issue one batch request, and store the results in a request-scoped map so repeated IDs resolve locally. The map must die with the request. It is a deduplication tool, not a shared cache.
Every downstream call must carry the caller's auth context and trace headers. Otherwise services cannot authorize the call or correlate its spans.
This design still amplifies load. One screen request becomes five, ten or more backend calls, and capacity planning has to account for that multiplier.
type Ctx = { auth: string; traceparent: string; deadline: number; signal: AbortSignal };
type Order = { id: string; items: { productId: string; qty: number }[] };
type Product = { id: string; name: string; price: number };
// Each call's timeout is whatever remains of the shared budget, minus a render margin.
async function call<T>(ctx: Ctx, url: string, reserveMs = 50): Promise<T> {
const remaining = ctx.deadline - Date.now() - reserveMs;
if (remaining <= 0) throw new Error(`no budget left for ${url}`);
const ctl = new AbortController();
const timer = setTimeout(() => ctl.abort(), remaining);
const onParentAbort = () => ctl.abort(); // request-wide cancel reaches this call too
ctx.signal.addEventListener("abort", onParentAbort, { once: true });
try {
// Forward the caller's identity and trace context on every downstream call.
const headers = { authorization: ctx.auth, traceparent: ctx.traceparent };
const res = await fetch(url, { signal: ctl.signal, headers });
if (!res.ok) throw new Error(`${url} -> ${res.status}`);
return (await res.json()) as T;
} finally { clearTimeout(timer); ctx.signal.removeEventListener("abort", onParentAbort); }
}
export async function orderDetail(orderId: string, customerId: string, auth: string, traceparent: string) {
const root = new AbortController();
const ctx: Ctx = { auth, traceparent, deadline: Date.now() + 800, signal: root.signal };
try {
// No data dependency between these three: start them together.
const [order, customer, loyalty] = await Promise.all([
call<Order>(ctx, `),
call(ctx, `),
call(ctx, `),
]);
// Dependent step: both need the order. Dedupe IDs, then one batch call instead of N.
const ids = [...new Set(order.items.map((i) => i.productId))];
const [shipment, products] = await Promise.all([
call(ctx, `)}`),
call<Product[]>(ctx, `","))}`),
]);
const byId = new Map(products.map((p) => [p.id, p] as const)); // request-scoped, dies with the request
const items = order.items.map((i) => ({ ...i, product: byId.get(i.productId) }));
return { order: { ...order, items }, customer, loyalty, shipment };
} finally { root.abort(); } // cancel any stragglers, e.g. siblings of a failed call
}
An order-detail composer that runs independent calls concurrently, chains order-dependent calls, sizes each timeout from a shared 800 ms budget, batches product lookups via a request-scoped map, and forwards auth and traceparent headers.
How should a BFF handle partial failure and tail latency?
Classify every field in the order-detail response before writing any handler. Order and customer data are required: without them the screen is meaningless, so the BFF returns an error. Shipment tracking and recommendations are optional: if they fail, the BFF still responds, and each section carries an explicit status such as ok, degraded or unavailable. A missing section should never look like an empty one.
Illustrative estimate (assumed inputs): the order service has a p99 of 120 ms, and customer lookup depends on it with a p99 of 80 ms. Shipment (300 ms) and recommendations (250 ms) run in parallel. The p99 path is roughly 120 + 80 + 300 = 500 ms, so the sequential chain plus the slowest dependency sets the floor. Fan-out makes this worse. If each call independently has a 1% chance of a p99-slow response, five calls give 1 − 0.99⁵ ≈ 4.9%, and ten give ≈ 9.6%. Put per-call timeouts and circuit breakers on optional dependencies so that a slow recommendations service gets skipped instead of consuming the budget.
Degraded responses have costs. Clients must render every combination of missing sections, and that logic needs tests. Retries also need a single owner. If both the BFF and the services retry, attempts multiply during an incident. Retry only at the BFF, under a retry budget.
Caching the whole screen fails in one of two ways. Short TTLs gain almost nothing. Long TTLs serve stale or leaked data, because invalidation depends on several upstream sources and on per-user data. Cache each upstream source separately, and include the user or tenant in the key wherever the data is user-specific.
// Section-level contract: a missing section is explicit, never an empty array.
type SectionStatus = "ok" | "degraded" | "unavailable";
interface Section<T> { status: SectionStatus; data: T | null; reason?: string }
interface OrderDetailResponse {
order: Order; // required: failure fails the whole request
customer: Customer; // required
shipment: Section<Shipment>; // optional: may be degraded or unavailable
recommendations: Section<Product[]>; // optional
}
// Wrap an optional dependency with a per-call timeout and a breaker check.
// There is no retry here. Retries are owned by the BFF's retry budget, not by each call site.
async function optional<T>(breaker: Breaker, call: () => Promise<T>, timeoutMs: number): Promise<Section<T>> {
if (breaker.isOpen()) return { status: "unavailable", data: null, reason: "circuit_open" };
let timer: ReturnType<typeof setTimeout> | undefined;
const timeout = new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
});
try {
const data = await Promise.race([call(), timeout]);
breaker.recordSuccess();
return { status: "ok", data };
} catch (err) {
breaker.recordFailure(); // repeated failures open the breaker, so later calls are skipped
return { status: "unavailable", data: null, reason: err instanceof Error ? err.message : "error" };
} finally {
clearTimeout(timer);
}
}
async function getOrderDetail(orderId: string, userId: string): Promise<OrderDetailResponse> {
const order = await orderService.get(orderId); // required and sequential: throws on failure
const [customer, shipment, recommendations] = await Promise.all([
customerService.get(order.customerId), // required
optional(shipmentBreaker, () => shipmentService.track(orderId), 300),
optional(recoBreaker, () => recoService.forUser(userId), 150), // tight budget: easy to skip
]);
return { order, customer, shipment, recommendations };
}
A BFF handler for the order-detail screen. It fails the request when a required section fails, while timeouts and circuit breakers on optional sections return them with an explicit status marker, so a slow optional dependency cannot consume the latency budget.
Who should own a BFF, and what does it cost to run one?
The frontend team that consumes a BFF should own it. A BFF's job is to translate domain data into what one client experience needs, and the people building that experience are best placed to decide its shape. That ownership comes with three boundaries. The BFF holds no domain business rules. It keeps no persistent domain state. Its endpoints map to screens or use cases, such as GET /screens/order-detail/{id}, rather than to entities. Split BFFs by client experience, for example one for web and one for mobile, not one per app or per team. Each extra BFF multiplies the problem described next.
How logic drift happens
Drift usually starts with a deadline. The web team needs a "free shipping eligible" badge, so it computes the rule in the web BFF. Later the mobile team copies it, and someone then changes the threshold in only one place. Pricing, eligibility and permission checks are the usual cases. Customers then see different answers on different devices.
Two guardrails prevent this:
- Push rules down into domain services. The BFF should receive
eligibleForFreeShipping: truefrom the service, not calculate it. - Review BFF code for domain logic. Treat conditionals on business values as a review flag.
Cost and payoff
Each BFF is another deployable. It needs on-call coverage, observability, security patching and capacity planning. Many frontend teams are not staffed to run production backends, so confirm they have that capacity before assigning ownership.
The payoff comes in three forms:
- Screen changes ship without coordinating changes to a shared gateway or to domain services.
- Clients receive smaller, simpler payloads.
- Mobile releases depend less on backend contract changes.
When should you use a BFF, a shared composition layer, or GraphQL?
A schema-driven layer such as GraphQL changes who writes the composition. In a BFF, a backend engineer writes one handler per screen. With a schema, the client declares the fields it needs, and resolvers map those fields onto domain services. The schema can replace thin BFFs entirely. It can also sit inside a BFF that still owns auth, session handling and client-specific policy.
That flexibility moves risk to the server. Any client can ask for deeply nested data. Production deployments therefore need:
- Depth and complexity limits, so one query cannot fan out into thousands of resolver calls.
- Persisted or allow-listed queries, so first-party clients send a query identifier and arbitrary queries are rejected.
Caching changes too. Most queries are POSTs to a single endpoint, so URL-keyed HTTP and CDN caching stops working. Caching moves into the server: per-request batching and deduplication of resolver calls, plus field- or entity-level caches keyed by type and ID.
| Situation | Favoured approach | Why |
|---|---|---|
| One client, few screens | Composition in one service or the gateway | A BFF adds a deployable with nothing to separate |
| Several clients with diverging needs and separate teams | One BFF per client | Each team ships screen changes on its own schedule |
| Many teams duplicating the same composition logic | Shared composition layer (often schema-driven), thin BFFs | Joins are written once; BFFs keep only client policy |
Avoid when
- BFF: frontend teams cannot own production services, or there is only one client.
- Gateway aggregation: many teams change screens independently, because the gateway becomes a shared bottleneck that every team must coordinate changes through.
- Client-side fan-out: mobile clients or public apps with slow update cycles. Every extra round trip costs latency, and a call pattern you ship to clients is hard to change later.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to backend for frontend pattern, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Consumers learn about a breaking change at review time rather than from production errors.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.