API Composition
API composition aggregates multiple service calls into one response through a composer that fans out in-memory, trading read availability for the weakest link of its providers.
Definition
API composition is the query-side pattern where a composer service invokes multiple provider services and joins their responses in memory to answer a query spanning their data. It suits queries over a few services with acceptable latency. Its availability multiplies the failure probabilities of every provider — the composer is only as available as its weakest dependency under a full-result requirement.
Context and scope
Used in microservice read paths where CQRS-style materialized views are not justified: product detail pages joining catalog, inventory, and reviews.
Common misconceptions
- The composer should call a shared database directly — that bypasses service ownership and recreates the distributed monolith data layer
- Composition scales to any number of services — latency and availability degrade multiplicatively; joins of many providers usually want a materialized view instead
- Failure of one provider fails the composition — partial-result policies degrade gracefully in many domains: hide the section, cache the last value
Anti-patterns
- Composing five-plus services synchronously for one page and shipping a p99 owned by the slowest
- Retrying provider calls without caching and multiplying load during provider incidents
- Returning partial data without flagging it, presenting incomplete results as authoritative
Related concepts
Authoritative source
What it is
A query needs data from three services. Either each service publishes into a shared read model (CQRS), or something asks all three and joins. The composer is that something — a query-side join in code.
How it works
The composer receives the request, invokes providers in parallel with per-call timeouts, and joins results by id. Resilience options: partial results with explicit staleness or absence flags, cached fallbacks for degraded providers, and hedged calls for stragglers. The composer owns no data, only the join logic.
When to choose
Reads spanning two or three services where fresh-enough data matters more than latency extremes, and where the read volume does not justify maintaining materialized views. Beyond that scale, prefer CQRS projections that pre-join the data once per write.
Pitfalls
Availability math: three providers at 99.9 percent yield roughly 99.7 percent for full-result composition — partial-result policies are the countermeasure, not optional polish. Join fan-out over collections multiplies calls: batch provider APIs or accept N+1-shaped latency. The composer silently becomes a business logic dumping ground — review its boundaries like any service.