An API composer implements a system query by synchronously calling provider services and combining their results into a client response. It addresses queries that need data owned by multiple services, where database-level joins across services are unavailable. section 12.0 section 12.2.1
The composer is application logic, not necessarily a separate service. Each provider owns part of the requested data and exposes service queries through its API. The composer decides which providers to call, what to request, in what order, and how to merge the results. section 12.2.1 section 12.3.2
Choose the composer’s location based on who uses the query and the complexity of aggregation:
- Service client: suitable for a frontend on the same LAN, but potentially impractical over a slower external network. section 12.3.1
- API gateway: suitable for an external query that should require only one client call. section 12.3.1
- Backend-for-frontend: suitable when the query is part of an API optimized for a particular frontend. section 12.3.1
- Standalone composition service: suitable for a query shared by multiple internal services or external aggregation too complex for the gateway. section 12.3.1
Order details and inconsistent results
A findOrder() query combines data from four provider services. Because their queries run independently, an order can appear cancelled while its kitchen ticket has not yet been cancelled. The composer must apply query-specific business semantics; for example, it might return the final CANCELLED order state. It may also need to return an order without ticket information if the ticket has not yet been created. section 12.3.3 section 12.3.2
API composition is the simplest distributed-query option when provider APIs and databases can efficiently supply the required data. Check the number of remote calls, response sizes, and join costs. A query requiring large in-memory joins or excessive round trips may be a poor fit; consider CQRS instead. section 12.2.1 section 12.4
Order history limitation
An order-history query filters and sorts using attributes distributed across services. Providers other than the Order Service cannot sort by order creation date, so a composer may have to retrieve and join every order since the cutoff before determining the requested page. section 13.1.1
Figure 13.1 API composition can’t efficiently retrieve a consumer’s orders because most providers, such as the Delivery Service, can’t sort and paginate their data by orderCreationDate, which forces the API composer to retrieve and join every order created since the cutoffDate.
The diagram illustrates why provider-side sorting and pagination limitations can force a large in-memory join. section 13.1.1
Multiple calls add network and database overhead, latency, and failure points. Independent provider transactions can also return inconsistent data. Use circuit breakers, time limiters, and appropriate fallbacks to reduce runtime coupling; invoke providers concurrently where possible to reduce latency. A fallback should return useful replacement data only when the query’s requirements permit it. section 12.2.4 section 12.3.3
