What is the API Composition pattern?
A composer (a gateway, a BFF or a dedicated service) receives a query, calls the services that own each part of the data, usually in parallel, and joins the results in memory. It replaces the database join you lost when each service got its own database.
What problem does the API Composition pattern solve?
With database per service, data for one screen lives in several places. Making the client call each service is slow and leaks your internal structure. A composer does the calls close to the services and returns one response.
How do you implement the API Composition pattern?
- Identify which service owns each part of the response.
- Call independent services in parallel, and only chain calls where one needs another's result.
- Set a time budget for the whole request and a timeout for each call within it.
- Decide per call whether it is required or optional, and return partial results when an optional call fails.
- Push filtering and pagination down to the owning services where you can.
When should you use it?
- A screen or endpoint needs data from a few services and the data must be current.
- The joined data is small enough to combine in memory.
When should you avoid it?
- The query filters or sorts across services over large data sets. Use a CQRS read model.
- Each request would fan out to many services in a chain.
What do you gain?
- Simple to build and understand
- Always returns current data
- Clients make one call
What does it cost?
- Latency is set by the slowest call
- Availability depends on every required service
- In-memory joins do not scale to large result sets
What are common mistakes with the API Composition pattern?
- Calling services one after another when they could be called in parallel.
- No timeouts, so one slow service holds every composed request.
- Treating every part of the response as required, so any failure fails the whole page.
API Composition in practice
Hearth Eats
The order tracking screen needed the courier's location, the restaurant's preparation status and the receipt, from three services. The mobile app made three calls over a slow network.
A composition endpoint calls the three services in parallel with a time budget and returns one response. If the receipt service is slow, the screen still shows location and status.
Example decision record
- Context
- The mobile dashboard makes six separate calls to render one screen.
- Decision
- Add a composition endpoint in the BFF that calls the services in parallel and returns one response.
- Consequences
- The client makes one round trip instead of six.
- The composer needs a time budget and a fallback for each non-critical call.