API Composition Pattern in Microservices

In a microservices architecture, data is deliberately partitioned across bounded contexts, where each service owns its private database. While this isolation prevents tight database coupling and supports independent deployment, it creates a fundamental query challenge: how do you assemble and render a unified response when the required data spans multiple independent microservices?

For example, displaying an e-commerce order details page may require:

• Basic order info and timestamps from the Order Service
• Transaction state and invoice details from the Payment Service
• Shipping status, carrier tracking, and ETA from the Logistics Service

The API Composition Pattern is an architectural pattern designed to solve this distributed query problem by delegating data aggregation to an intermediary composer.

---

The Distributed Query Challenge

Consider an e-commerce architecture where an end-user needs granular details about an order:

flowchart LR
    subgraph Without Composer [Client-Side Aggregation]
        C[Client Device] -->|1. Fetch Order| OS1[Order Service]
        C -->|2. Fetch Payment| PS1[Payment Service]
        C -->|3. Fetch Tracking| LS1[Logistics Service]
    end

The Problem with Client-Side Aggregation

If the client (browser or mobile application) orchestrates these calls directly, several operational and performance issues arise:

1. High Latency from Multiple WAN Round Trips: Network round-trip times (RTT) over wide-area networks (WAN) and cellular connections are orders of magnitude slower than intra-datacenter networks. Making multiple sequential or parallel network hops across thousands of kilometers significantly degrades perceived latency.
2. Bandwidth and Battery Consumption: Mobile clients transmit duplicate request headers, perform multiple TLS handshakes, and process redundant JSON payloads, draining battery life and consuming cellular data.
3. Tight Coupling to Backend Topology: The client must maintain awareness of internal microservice endpoints, routing rules, and authentication schemes. Any backend refactoring or split requires client updates.
4. Complex Client-Side Join Logic: Merging disparate JSON structures, handling partial failure scenarios, and reconciling inconsistent keys must be written into client applications across multiple platforms (iOS, Android, Web).

---

The API Composition Architecture

The API Composition pattern resolves these issues by inserting an in-memory aggregation layer—a composer—between the client and the downstream microservices.

flowchart TD
    Client[Client / Mobile App / Web]
    Client -->|Single Request: GET /orders/:id/details| Composer[API Composer / Gateway]
    
    subgraph Internal Network [Low-Latency Internal Network]
        Composer -->|Query 1| OS[Order Service]
        Composer -->|Query 2| PS[Payment Service]
        Composer -->|Query 3| LS[Logistics Service]
    end

How It Works

1. The client sends a single HTTP/gRPC request to the composer.
2. The composer receives the request, parses the query parameters, and determines the downstream dependencies.
3. The composer executes calls to the downstream services over the low-latency internal network (LAN/VPC).
4. The composer joins and formats the individual payloads into a single, unified response schema.
5. The compiled response is returned to the client in a single round trip.

Off-the-Shelf vs. Custom Composers

You rarely need to write a composer from scratch. Established options include:

• API Gateways: Production-grade gateways like KrakenD and Kong support declarative response aggregation and transformation out of the box.
• Cloud-Managed Gateways: AWS API Gateway, Azure API Management, and Google Cloud Apigee.
• BFF (Backend-For-Frontend) Services: A lightweight custom service (written in Go, Node.js, or Java) designed specifically to cater to the presentation needs of a given client platform.

---

Execution Strategies: Sequential vs. Parallel Fan-Out

When the composer aggregates data across downstream services, it can orchestrate calls sequentially or in parallel.

flowchart TD
    subgraph Sequential [Sequential Orchestration]
        S_Start([Start]) --> S1[Call Service A] --> S2[Call Service B] --> S3[Call Service C] --> S_End([End: Total Latency = T_A + T_B + T_C])
    end

flowchart TD
    subgraph Parallel [Parallel Fan-Out Orchestration]
        P_Start([Start]) --> P_Fork{Fork Calls}
        P_Fork --> P1[Call Service A: T_A]
        P_Fork --> P2[Call Service B: T_B]
        P_Fork --> P3[Call Service C: T_C]
        P1 --> P_Join{Join / Await All}
        P2 --> P_Join
        P3 --> P_Join
        P_Join --> P_End([End: Total Latency = max T_A, T_B, T_C])
    end

1. Sequential Execution

• Mechanism: The composer invokes downstream services one after another.
• When to Use: Required when dependency chaining exists—e.g., retrieving an order_id from the Order Service before the Payment Service can query transaction records by that ID.
• Trade-off: High overall latency ($T_{\text{total}} = \sum T_i$). However, it consumes minimal concurrent machine resources (threads and sockets).

2. Parallel Fan-Out

• Mechanism: The composer spawns concurrent tasks or threads to query independent services simultaneously, joining the responses once all promises/futures resolve.
• When to Use: When all required input arguments are already available in the initial client request.
• Trade-off: Minimal latency ($T_{\text{total}} \approx \max(T_i)$). However, excessive parallel fan-out can strain gateway resources:
  • CPU & Core Saturation: True hardware parallelism is strictly bounded by available CPU cores. Spinning up unbounded worker threads can cause high context-switching overhead.
  • Runtime & Language Constraints: Languages with Global Interpreter Locks (like standard CPython) do not achieve multi-core parallel thread execution without multiprocess architectures. Runtimes with asynchronous I/O (Node.js) or lightweight green threads/goroutines (Go) handle network I/O fan-out much more efficiently.

3. Hybrid Orchestration

In practice, architectures often use a hybrid model: parallelize independent calls where possible, and sequence dependent queries only when mandatory.

---

Multi-Level API Composition

As organizations and microservice architectures scale, composition is rarely confined to a single level. Downstream services may themselves act as composers for internal domain services.

flowchart TD
    Client --> Composer[Edge API Gateway]
    Composer --> PaymentService[Payment Service]
    Composer --> OrderService[Order Service]
    
    subgraph Sub-Domain Composition [Internal Composition]
        OrderService --> SellerService[Seller Service]
        OrderService --> InventoryService[Inventory Service]
    end

In this nested structure:

• The API Gateway composes at the edge level.
• The Order Service acts as an internal domain composer, querying the Seller and Inventory services before completing its own contract.

While multi-level composition naturally reflects organizational domain boundaries, it compounds latency and failure propagation risk. Deeply nested composition chains should be audited to prevent latency inflation.

---

Advantages of API Composition

1. Simplified Client Experience: Front-end applications interact with a clean, single-point-of-contact interface, minimizing client-side network management and parsing logic.
2. Reduced Network Overhead: Consolidates multiple cross-continent WAN hops into a single round trip, delegating subsequent queries to high-throughput, low-latency internal infrastructure.
3. Encapsulation & Decoupling: Hides internal service topology, data models, and refactoring changes behind an abstraction layer.
4. Centralized Edge Governance: Serves as a single enforcement point for cross-cutting operational concerns, such as:
   • Authentication and authorization verification
   • Rate limiting, throttling, and DDoS protection
   • Distributed tracing injection (traceparent propagation)
   • Edge-level payload caching
5. Anti-Corruption Layer (ACL) for Legacy APIs: If a backend microservice yields poorly structured or non-standard payloads due to rapid MVP development, the composer can reshape, filter, and adapt the schema before exposing it to the UI.
6. Enabler of the Strangler Fig Pattern: When migrating from a legacy monolith to microservices, a composer can dynamically route requests—forwarding /payments to the new microservice while delegating all other routes to the legacy monolith—without affecting client configurations.

---

Disadvantages and Operational Pitfalls

Despite its simplicity, API Composition introduces notable architectural trade-offs:

1. In-Memory Data Aggregation Bottlenecks

When downstream services return large payloads, joining them in memory can consume significant RAM on the composer.

Example: Consider a blogging platform where an edge composer requests 10 full-length articles along with their respective comment threads and reaction counts. Merging several megabytes of unstructured text across multiple concurrent requests can cause rapid heap inflation, triggering aggressive garbage collection cycles or Out-Of-Memory (OOM) crashes on the gateway.

2. Availability Compounding (Cascading Degradation)

If the composer depends on three services ($S_1, S_2, S_3$) to assemble a mandatory response, the availability of the aggregated endpoint ($A_{\text{total}}$) is the mathematical product of the downstream availabilities:

$A_{\text{total}} = A(S_1) \times A(S_2) \times A(S_3)$

If each service has an availability of $99.9\%$, the composite availability drops to:

$0.999 \times 0.999 \times 0.999 \approx 99.7\%$

To prevent the outage of a secondary service (e.g., reaction counters) from bringing down the entire view, the composer must implement graceful degradation through fallbacks, circuit breakers, and partial response contracts.

3. Lack of Distributed Transactional Consistency

API Composition operates at the query level; it does not provide distributed atomicity (ACID properties). If composition logic is used to execute multi-phase write operations across services, an intermediate failure leaves the system in an inconsistent state. Operations requiring transactional guarantees across bounded contexts must rely on the Saga Pattern or distributed event-driven choreography rather than basic API composition.

4. Operational Bottlenecks and Single Points of Failure (SPOF)

Because all client ingress traffic passes through the composition layer, misconfigurations, CPU saturation, or network connection pool exhaustion can degrade the entire application ecosystem. Composers must be deployed with horizontal autoscaling, redundant instances, robust connection pooling, and strict request timeouts.

---

Comparison: API Composition vs. Alternative Patterns

Criteria	API Composition	CQRS (Command Query Responsibility Segregation)	Client-Side Fan-Out
Implementation Complexity	Low to Moderate	High (Requires dedicated read stores, event sourcing/projections)	Low (Transfers burden to client)
Query Latency	Dependent on the slowest service + join overhead	Very Low (Pre-joined, materialized read views)	High (Multiple WAN network round trips)
Data Freshness	Real-time (Queries current operational state)	Eventually Consistent (Lag introduced by event propagation)	Real-time
Resource Footprint	Concentrated in Composer RAM/CPU	Concentrated in Storage & Projection Pipelines	Distributed across end-user devices
Best For	Operational read queries, low-to-medium dataset sizes, quick iterations	High-throughput, complex multi-entity joins, large historical datasets	Internal developer tooling, rapid prototyping

---

Key Architectural Takeaways

• Keep In-Memory Joins Lightweight: Use API Composition for small-to-medium relational stitching. If queries require massive multi-table joins or historical analytical scans, migrate to CQRS with pre-aggregated read views.
• Design for Partial Failure: Never allow non-critical downstream dependencies to block a composite response. Use timeouts, circuit breakers, and fallback defaults.
• Monitor Edge Saturation: Ensure your composer runtime (Go, Node.js, Envoy, KrakenD) uses non-blocking I/O and has clear resource bounds for concurrent connections and heap allocations.