liveBook · Manning

API composition

As explained in Microservices Patterns, Second Edition

A service collaboration pattern that invokes multiple service APIs and combines their results into a response.

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.
ApiCompositionBasedQueryBigPicture

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

How Microservices Patterns, Second Edition covers it

How deep it goes
Explains participants, manual query planning, consistency handling, resilience, and efficiency trade-offs.
Examples
Illustrates an order query that joins responses from four provider services using an order ID.
What you can do after
Evaluate whether provider capabilities, availability, consistency, and data-transfer costs make API composition suitable for a query.
How it connects
Connects distributed queries to CQRS, circuit breakers, time limiters, and fallback.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.