Chapter 12: Using the API Composition pattern to implement system queries
The introduction explains why queries spanning multiple services need application-level collaboration rather than database-level joins or distributed transactions.
After this chapter you will be able to
- Distributed query constraints. Explain why a system query that retrieves data from multiple services cannot rely on a distributed transaction or a database-level join.
- Query collaboration patterns. State that distributed system queries must use service collaboration patterns, identifying API Composition and CQRS as the two patterns named here and explaining where they put the complexity.
- Single-query frontend approach. Justify using one system query, such as findOrder(), rather than having the mobile app invoke a query per subdomain. Explain the effects on client logic, coupling to the backend’s subdomain structure, and network round trips.
- findOrder query contract. Describe what findOrder() takes and returns, how FTGO could expose it, and why its implementation can vary by architecture.
- Isolation for read-only queries. Explain why a system query needs transaction management even though it does not update data: isolation lets it read a consistent database snapshot rather than a mix of values from different moments.
- Two levels of query isolation. Distinguish statement-level isolation from transaction-level isolation: the first gives one SQL statement a consistent snapshot, while the second gives a transaction containing multiple SELECTs a consistent snapshot throughout.
- Single-database order retrieval. Explain how a monolithic FTGO application can implement findOrder() with one or more SELECT statements against a single database, potentially using a join across tables. Describe why a cross-subdomain join can be a worthwhile tradeoff despite violating domain module boundaries.
- Whole-query transactional isolation. Explain why a monolith can run the entire system query within a transaction to ensure data consistency, and identify the local data and centralized transaction manager as the reasons.
- Cross-service join restriction. Explain why findOrder() cannot join data across service databases and must instead use API-based collaboration.
- Independent query transactions. Explain why findOrder() cannot run as one ACID transaction across services and how the participating services execute their portions of the query.
- System query collaboration patterns. Distinguish how API composition and CQRS obtain data for a system query.
- Consistency and efficiency comparison. Explain the section’s comparison of the patterns’ simplicity, possible efficiency, and consistency.
- API Composition Participants and Flow. Explain how an API composer implements a system query by calling provider-service queries through synchronous APIs and combining their results. Distinguish the composer logic, the service containing it, and the providers that own the data.
- Find Order Composer request flow. Trace how the Find Order Composer handles GET /orders/{orderId}: it calls four provider services through their APIs and joins their responses on orderId. Distinguish the Order Service’s primary-key lookup from the other providers’ foreign-key lookups.
- Straightforward query composition. Explain why API composition is often straightforward to implement when query data is scattered across services: composer logic invokes each service using synchronous request/response.
- Reading your own writes. Explain what it means for API composition clients to read their own writes and contrast that guarantee with queries against eventually consistent replicas.
- Availability across participating services. Explain why involving more services can reduce an API-composed query's availability, and describe the limited responses the stated resiliency patterns enable.
- Cross-service consistency risk. Explain how a composed query can return inconsistent data during a concurrent command, using the findOrder() example.
- Limits of query composition. Describe why some system queries are inefficient to implement with API composition and identify the alternatives stated here.
- Client versus gateway composition. Distinguish when a service client can act as the API composer from when composition in the API gateway makes more sense.
- Standalone composition service use. Explain when to put an API composer in a standalone service.
- Manual composition query planning. Explain how designing API composition resembles manual query planning: analyze the system query and available provider data, then choose which services to call, what to request, the call order, and how to merge the results. Describe the tradeoffs among remote calls, response size, and latency.
- Inconsistent result handling. Describe how composition logic can handle conflicting service states or unmatched records, and explain why the query’s semantics and business requirements determine the choice.
- Resiliency patterns in provider proxies. Describe how provider proxies use resiliency patterns when an API composer makes synchronous calls, and distinguish failing fast from returning a usable response.
- Fallback choices and coupling limits. Explain the two fallback choices for an unavailable provider, their tradeoffs, and why fallbacks cannot eliminate all runtime coupling.
- Concurrent provider call design. Explain when an API composer can call providers in parallel, how that changes latency, and when dependencies require sequential calls.
What it builds on
- Handling saga’s lack of isolation (chapter 9) · The significance of isolation when transactions execute concurrently.
- Design-time coupling (chapter 4) · The importance of loose design-time coupling.
- Implementing resilient synchronous communication (chapter 8) · Resilient synchronous communication.
Section by section
Introduction
The introduction explains why queries spanning multiple services need application-level collaboration rather than database-level joins or distributed transactions.
- Distributed query constraints: Explain why a system query that retrieves data from multiple services cannot rely on a distributed transaction or a database-level join.
Why it matters: This constraint explains why querying across services needs a different design from querying one database. - Query collaboration patterns: State that distributed system queries must use service collaboration patterns, identifying API Composition and CQRS as the two patterns named here and explaining where they put the complexity.
Why it matters: It frames API Composition as one application-level response to the limits of querying across service boundaries.
Key terms: distributed system queries, ACID transaction boundary, database-level joins, service collaboration patterns, API Composition, CQRS
12.1 The challenge of querying in the microservice architecture
Introduces the challenges of querying data across microservices and previews the approaches covered in the section.
12.1.1 System queries typically support the UI
The section uses FTGO’s Order Details view to show why a UI query should return information from multiple subdomains without making the frontend query each one separately.
- Cross-subdomain UI information: Describe why the FTGO mobile app needs a system query for its Order Details view: the view combines order, payment, restaurant, and delivery information from multiple subdomains.
Why it matters: The view’s information needs explain why fetching its data is more than a simple single-subdomain request. - Single-query frontend approach: Justify using one system query, such as findOrder(), rather than having the mobile app invoke a query per subdomain. Explain the effects on client logic, coupling to the backend’s subdomain structure, and network round trips.
Why it matters: One query lets the mobile app request what its view needs without taking on cross-subdomain retrieval logic.
Key terms: Order Details view, system queries, subdomains, single system query, findOrder(), network round trip
12.1.2 The findOrder() system query
This section defines the findOrder() system query and notes that its implementation depends on the application’s architecture.
- findOrder query contract: Describe what findOrder() takes and returns, how FTGO could expose it, and why its implementation can vary by architecture.
Why it matters: This query is the concrete example used to discuss how architecture affects system queries.
Key terms: findOrder(), orderId, OrderDetails, GET /orders/{orderId}
12.1.3 Why system queries need to be transactional
This section explains why read-only system queries need isolation, how consistency applies within one statement and across multiple statements, and why database isolation defaults matter.
- Isolation for read-only queries: Explain why a system query needs transaction management even though it does not update data: isolation lets it read a consistent database snapshot rather than a mix of values from different moments.
Why it matters: A query can return an inconsistent result even when it changes nothing. - Two levels of query isolation: Distinguish statement-level isolation from transaction-level isolation: the first gives one SQL statement a consistent snapshot, while the second gives a transaction containing multiple SELECTs a consistent snapshot throughout.
Why it matters: Keeping each SELECT consistent is not the same as keeping a multi-SELECT query consistent as a whole. - Database isolation defaults and tradeoff: Explain that modern databases may relax isolation below true serializability by default to gain throughput, while some provide efficient transaction-level snapshot isolation for short-lived read-only queries.
Why it matters: A query’s consistency guarantees cannot simply be assumed from the fact that it runs in a modern database.
Key terms: system query, isolation, consistent snapshot, ACID, statement-level isolation, transaction-level isolation, SQL SELECT, serializable isolation, isolation levels, throughput
12.1.4 Implementing findOrder() in a monolith is straightforward
Explains why a monolith can retrieve order details and provide a consistent result for findOrder() using its single database and centralized transaction manager.
- Single-database order retrieval: Explain how a monolithic FTGO application can implement findOrder() with one or more SELECT statements against a single database, potentially using a join across tables. Describe why a cross-subdomain join can be a worthwhile tradeoff despite violating domain module boundaries.
Why it matters: This establishes why findOrder() is relatively simple in a monolith. - Whole-query transactional isolation: Explain why a monolith can run the entire system query within a transaction to ensure data consistency, and identify the local data and centralized transaction manager as the reasons.
Why it matters: The monolith’s ability to isolate the whole query is an important contrast with the microservice architecture.
Key terms: findOrder(), SELECT statements, joins, domain module boundaries, transaction, data consistency, transactional isolation, transaction manager, @Transactional
12.1.5 Challenges implementing findOrder() in a microservice architecture
This section explains why findOrder() is harder to implement across microservices: its data is scattered across services, which cannot use cross-service joins or a single ACID transaction.
- Distributed findOrder data: Describe why findOrder() is a distributed system query and identify the kinds of order information it must retrieve from different services.
Why it matters: The scattered data is what makes this a distributed query rather than an ordinary single-service query. - Cross-service join restriction: Explain why findOrder() cannot join data across service databases and must instead use API-based collaboration.
Why it matters: This restriction determines how services can obtain one another’s data for a system query. - Independent query transactions: Explain why findOrder() cannot run as one ACID transaction across services and how the participating services execute their portions of the query.
Why it matters: A query spanning services cannot assume that all its reads occur within one shared transaction.
Key terms: distributed system query, findOrder(), Order Service, Kitchen Service, Delivery Service, Accounting Service, joins across services, APIs, loose design-time coupling, API-based collaboration
12.1.6 Overview of the service collaboration patterns for queries
Introduces API composition and CQRS as two ways to implement system queries, and summarizes their consistency tradeoffs.
- System query collaboration patterns: Distinguish how API composition and CQRS obtain data for a system query.
Why it matters: The two patterns answer the same kind of query but obtain its data in different ways. - Consistency and efficiency comparison: Explain the section’s comparison of the patterns’ simplicity, possible efficiency, and consistency.
Why it matters: Neither the simpler option nor the use of ACID transactions guarantees a fully consistent system query. - Decomposition consistency tradeoff: Justify why the section accepts eventual consistency and state its suggested response to problematic query results.
Why it matters: It frames inconsistent results as an architectural tradeoff that can be improved by changing service boundaries.
Key terms: API composition, CQRS, services that own the data, replica database, change events, eventually consistent, ACID transactions, decomposition into services, eventual consistency, service boundaries
12.2 Using the API composition pattern
12.2.1 Overview of the API Composition pattern
This section explains how API Composition answers a system query by combining data from provider services, and why the approach is not feasible for every query.
- API Composition Participants and Flow: Explain how an API composer implements a system query by calling provider-service queries through synchronous APIs and combining their results. Distinguish the composer logic, the service containing it, and the providers that own the data.
Why it matters: It shows how a query can assemble an answer without one service owning all the required data. - API Composition Feasibility Limits: Describe what determines whether API Composition is practical for a particular query, including provider database and API capabilities and the cost of combining results.
Why it matters: Calling several services is only useful if they can supply the needed data and their results can be combined efficiently.
Key terms: API composer, API composition service, provider services, service queries, synchronous request/response, service query, in-memory join, API Composition
12.2.2 Implementing the findOrder() system query using the API composition pattern
Shows why findOrder() suits API composition and how a composer joins data retrieved from four provider services.
- Suitability of findOrder for composition: Justify using API composition for findOrder(): it is a simple equijoin on orderId, and each provider can reasonably expose an API for retrieving its required data by that ID.
Why it matters: This explains why the composer can assemble the query result from provider responses. - Find Order Composer request flow: Trace how the Find Order Composer handles GET /orders/{orderId}: it calls four provider services through their APIs and joins their responses on orderId. Distinguish the Order Service’s primary-key lookup from the other providers’ foreign-key lookups.
Why it matters: The request flow shows how a query spanning services can be answered without treating their data as one database.
Key terms: findOrder(), API composition pattern, orderId, equijoin query, Find Order Composer, GET /orders/{orderId}, Provider service, primary key, foreign key
12.2.3 Benefits
This section explains two benefits of API composition: it is often straightforward to implement, and clients can read their own writes.
- Straightforward query composition: Explain why API composition is often straightforward to implement when query data is scattered across services: composer logic invokes each service using synchronous request/response.
Why it matters: This explains why API composition can be a practical way to answer a query spanning services. - Reading your own writes: Explain what it means for API composition clients to read their own writes and contrast that guarantee with queries against eventually consistent replicas.
Why it matters: A client can see the result of its command in a follow-up query rather than an older value.
Key terms: API composer logic, synchronous request/response, read their own writes, eventually consistent replicas, primary data
12.2.4 Drawbacks
This section explains the performance, availability, consistency, and query-fit drawbacks of API composition.
- Multiple-request query overhead: Explain why API composition has more overhead than a query local to one service.
Why it matters: Combining data from services can cost more than reading it locally. - Availability across participating services: Explain why involving more services can reduce an API-composed query's availability, and describe the limited responses the stated resiliency patterns enable.
Why it matters: A composed query has more service dependencies than a local query, though it can sometimes return a useful response despite a provider failure. - Cross-service consistency risk: Explain how a composed query can return inconsistent data during a concurrent command, using the findOrder() example.
Why it matters: A response assembled from several services can contain facts that do not represent one consistent moment. - Limits of query composition: Describe why some system queries are inefficient to implement with API composition and identify the alternatives stated here.
Why it matters: Not every cross-service query is practical to implement by fetching provider data and combining it.
Key terms: API composition pattern, overhead, TLS-based communication, API composer, provider services, availability, Circuit Breaker pattern, Fallback pattern, transactional data consistency, ACID database transaction
12.3 API composition design issues
This section introduces the design issues to be addressed when implementing API composition.
12.3.1 The location of the API composer
This section explains where an API composer can be located and how the query’s clients and aggregation needs guide that choice.
- Client versus gateway composition: Distinguish when a service client can act as the API composer from when composition in the API gateway makes more sense.
Why it matters: The composer’s location affects how efficiently different clients can retrieve data from multiple services. - Frontend-specific BFF composition: Describe how a Backend-for-frontend can host an API composer for a particular frontend.
Why it matters: A BFF is a composition location when the API is tailored to one kind of frontend. - Standalone composition service use: Explain when to put an API composer in a standalone service.
Why it matters: Not every shared or complex query belongs in a client or gateway.
Key terms: service client, API composer, API gateway, external API, Backend-for-frontend (BFF), API composition, composition service, system query, aggregation logic
12.3.2 Designing the provider queries and composition logic
This section explains how to plan provider queries and composition logic, handle inconsistent results, and coordinate with teams that own provider services.
- Manual composition query planning: Explain how designing API composition resembles manual query planning: analyze the system query and available provider data, then choose which services to call, what to request, the call order, and how to merge the results. Describe the tradeoffs among remote calls, response size, and latency.
Why it matters: A composition can produce the right answer yet still be too slow or expensive because of its service calls. - Inconsistent result handling: Describe how composition logic can handle conflicting service states or unmatched records, and explain why the query’s semantics and business requirements determine the choice.
Why it matters: A response assembled from individually valid service results may still misrepresent the business state unless the composer handles inconsistencies deliberately. - Provider team collaboration: Explain why a query spanning services owned by other teams may require collaboration to define new provider queries or improve existing ones.
Why it matters: The composer’s design may depend on API work that its own team cannot make alone.
Key terms: provider queries, composition logic, query planner, remote calls, inconsistent results, inner join, outer join, partial data, service queries, collaborate
12.3.3 Resilient and performant API Composition
This section explains how API composers can limit provider failures and query latency through resiliency patterns, fallbacks, and concurrent calls.
- Provider coupling and latency risks: Explain why synchronous API composition can make a query brittle and slow, using the findOrder() query as an example.
Why it matters: These risks explain why an API composer needs both failure handling and latency reduction. - Resiliency patterns in provider proxies: Describe how provider proxies use resiliency patterns when an API composer makes synchronous calls, and distinguish failing fast from returning a usable response.
Why it matters: Failing fast limits the effect of a troubled provider, while a fallback can keep the query useful. - Fallback choices and coupling limits: Explain the two fallback choices for an unavailable provider, their tradeoffs, and why fallbacks cannot eliminate all runtime coupling.
Why it matters: A fallback is useful only when its substitute data still serves the user’s query. - Concurrent provider call design: Explain when an API composer can call providers in parallel, how that changes latency, and when dependencies require sequential calls.
Why it matters: Parallelizing independent calls reduces query latency without ignoring dependencies between providers.
Key terms: runtime coupling, synchronous communication, provider services, latency, provider proxy, Circuit breaker, Time limiter, Bulkhead, fail-fast, Fallback pattern
12.4 Summary
Where this is used later
- Overview of the CQRS pattern (chapter 13) · Explains CQRS, the other query pattern named here.
- Distributed queries that can’t use the API Composition pattern (chapter 13) · The findOrder() query used for comparison
- The benefits of the CQRS pattern (chapter 13) · Expands on the benefits of CQRS.
Concepts explained in this chapter
- API composerAn API composer invokes multiple service APIs and combines their results into a client response.
- API compositionA service collaboration pattern that invokes multiple service APIs and combines their results into a response.
- providerA provider service is a service that owns some of the data returned by a distributed query and exposes that data through an API.
- circuit breaker patternA circuit breaker pattern stops calls to a failing dependency for a period and later permits test calls to determine whether it has recovered.
- fallbackA fallback pattern supplies a degraded but useful result when the primary operation or dependency fails.
- queryA system operation that retrieves application data without mutating it.
- distributed query executionA data-retrieval operation whose required data resides across multiple services.
- concurrencyConcurrency is the condition in which multiple operations or transactions execute during overlapping periods of time.
- reactive architectureReactive design structures software around asynchronous, nonblocking abstractions that represent and compose results over time.
- resiliency patternA resiliency pattern is a design technique that limits the impact of failures, overload, or excessive latency in a distributed system.
- structured concurrencyStructured concurrency is a concurrency model that scopes concurrent tasks within a well-defined lifetime and hierarchy.
- service queryA service API operation that retrieves data needed by a query composed across multiple services.
- CQRSA distributed query pattern that maintains a read-only queryable replica combining data from multiple services.
- availabilityThe degree to which a system or service is operational and accessible when required.
- consistencyConsistency is the transaction property that a committed transaction leaves the system in a valid state while preserving defined invariants and constraints.
- contractAn interface that defines how software components interact and access one another's functionality.
- service collaboration patternA recurring architectural solution for coordinating interactions and distributed operations among services.
- distributed transactionA transaction identified and coordinated across multiple participating resource managers.
- nondistributed transactionA local transaction is a transaction whose scope is restricted to the data and resources managed by one service.
- transaction boundaryA transaction boundary defines the scope within which operations are governed by rules for success, failure, concurrency, conflicts, and visibility.
- api composition serviceAn API composition service is a service that contains the API composer responsible for implementing a system query.
- isolationA database transaction setting that determines which effects of concurrent transactions may be observed.
- transaction managementTransaction management is the coordination of transactional operations to preserve the required consistency and completion semantics of data changes.
- database transactionA unit of work whose operations execute under defined consistency and completion semantics.
- monolithic architectureAn architecture in which an application is built and deployed as a single unit.
- synchronous callSynchronous code performs operations in a sequence that waits for each operation to complete before continuing.
- bulkheadA bulkhead pattern isolates resources used by different operations or dependencies so that one failure or overload does not exhaust shared capacity.
- cachingA caching pattern stores previously obtained data so that subsequent requests can be served without accessing the original provider.
- proxyA provider proxy is an intermediary component that invokes a provider service and applies behavior such as resiliency controls or fallback handling.
- rate limitA rate limiter pattern restricts the frequency or volume of calls made to a resource or dependency.
- retryA retry mechanism is logic that repeats a failed operation to recover from transient failures.
- time limiterA resiliency pattern that bounds how long an operation may wait for completion before it is treated as failed.
- service boundaryA service boundary is a division that defines the responsibilities and scope of a service within a distributed application.
- clientA service client is a software component that invokes one or more service APIs on behalf of a user interface or application.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
