API composition implements a distributed query by calling the APIs of services that own the required data and combining their responses. It addresses the lack of database-level joins across service boundaries, but moves query planning and consistency handling into application logic. section 12.0 section 12.2.1
An API composer makes synchronous request/response calls to provider services, then merges their results. The composer can live in a client, API gateway, backend-for-frontend, or standalone composition service. Providers expose the service queries needed to retrieve their own data. section 12.2.1 section 12.4
Figure 12.5 The API composition pattern consists of an API composer and two or more provider services. The API composer implements a query by querying the providers via their APIs and combining the results.
The diagram shows the composer querying provider services and combining their results. section 12.2.1
Retrieve an order
A gateway exposes GET /orders/{orderId}. Its composer calls four provider services and joins their responses by orderId. The Order Service retrieves its order by primary key; the other providers use orderId as a foreign key. section 12.2.2
Designing a composition is manual query planning: choose providers, requested data, call order, and merge logic. Balance remote calls, response sizes, and latency. Teams may need to coordinate when providers have different owners. section 12.3.2
Evaluate the trade-offs before choosing the pattern:
- It is often straightforward and lets clients read their own writes after a completed command, unlike queries against replicas that may lag. section 12.2.3
- Multiple calls and database queries add overhead. Complete responses depend on provider availability, and independent transactions do not give a consistent cross-service snapshot. section 12.2.4
- Provider APIs and databases must support the required queries. Large transfers, many round trips, or large in-memory joins can make composition inefficient. section 12.2.1 section 12.4
Define how to handle inconsistent results: an order might be cancelled while its associated ticket has not yet been cancelled. Use circuit breakers, time limiters, and carefully chosen fallbacks to handle provider failures; invoke providers concurrently where possible to reduce latency. section 12.3.2 section 12.3.3
Prefer API composition when provider queries and result sizes make it practical. For queries where composition is too inefficient or infeasible, consider CQRS, which maintains a queryable read-only replica combining data from multiple services. section 12.4 section 7.6.2
