Composed APIs: Aggregating Other Services

A composed endpoint is a fan-out: GET /orders/42/full calls the orders service, then users, catalog and shipping in parallel. The client saves round trips — that is the whole point, and on mobile networks it is a large point (see API Granularity and the Chatty API). The provider inherits the physics: the composed response is as slow as its slowest dependency, and its availability is, naively, the *product* of theirs. Four dependencies at 99.9% make a naive composition 99.6% — from under nine hours of downtime a year to almost thirty-five.

Latency composes by tails, not means. If each dependency answers in 20ms at p50 but 400ms at p99, an endpoint awaiting all four hits a 400ms straggler in roughly 4% of requests — the fan-out samples every dependency's tail on every call. The composition contract therefore needs per-dependency timeouts and an overall budget ("answer within 300ms with whatever has arrived"), not just an aspiration.

None of this argues against composition; it prices it. The alternative — every client fanning out itself — pays the same physics plus N× the RTTs from a worse network position, and scatters the failure handling across every consumer. Composition centralizes the problem where it can actually be solved. The question the contract must answer is *how* it is solved.

Shipping is down. What does GET /orders/42/full return? The four candidate answers are all defensible and mutually exclusive: fail the whole request (honest, brittle — one optional section kills the page); return the field as null (indistinguishable from "no shipping info exists"); omit the field (breaks clients that require it); or return the section with explicit degradation metadata. The only wrong move is not choosing — because then the behavior is whatever the composer's error handling happens to do, and clients discover it during the dependency's next outage.

The durable pattern splits dependencies into required (the order itself — without it there is no response, fail with 503 and honest retry guidance) and optional (enrichments — degrade explicitly). Explicit degradation means the response says which sections are missing and why, so the UI renders "shipping status temporarily unavailable" instead of a blank, and monitoring can count degraded responses instead of confusing them with healthy ones. Stale-as-fallback (serve the last cached shipping status, labeled stale) is often better than absent — a freshness statement per section makes that honest (see Consistency as a Contract Clause).

A composed endpoint couples its owner to every dependency's contract, capacity and release schedule. Each dependency's breaking change is now the composer's incident; each dependency's p99 regression is the composer's SLO burn. That coupling needs an owner — a team accountable for the composed contract, with tracked-consumer relationships to each dependency (API Ownership and the Catalog applies one level down). Composition without ownership produces the org's most-blamed, least-staffed endpoint.

Where to compose is an architectural choice with three usual homes: a Backend for Frontend when the aggregate is experience-shaped and one client team owns it; a domain service when the aggregate is a real domain concept ("order summary") used by many consumers; a gateway-level composition only for thin, mechanical joins (see The Gateway as Policy Boundary — gateways should apply policy, not business assembly). And sometimes the answer is not to compose: two calls the client can make in parallel cost one RTT extra and zero coupling; a composition that saves nothing but an await is pure liability.

Watch the depth. Composers calling composers stack tail latencies and multiply blast radius; a three-deep chain gives the leaf service the power to take down every aggregate above it. Keep composition shallow — composers call capability services, not other composers — and let dependency-count growth trigger a design review rather than another Promise.all entry.