Architecture
An API composition architecture diagram with a composer service that fans out parallel requests to multiple microservices, collects responses with timeout handling, and merges results into a single unified response with partial fallback support. This template models the API composition pattern used when a single client query requires data from multiple services, avoiding the need for direct service-to-service calls. Useful for teams building aggregation layers in microservices architectures.
Full FlowZap Code
Client { # Client Application
n1: circle label:"Complex Query Request"
n2: rectangle label:"API Composer Service"
n3: rectangle label:"Receive Composed Response"
n4: circle label:"End"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> Composer.n5.handle(top) [label="Compose"]
n3.handle(right) -> n4.handle(left)
}
Composer { # API Composition Layer
n5: rectangle label:"Parse Query Requirements"
n6: rectangle label:"Fan-Out Parallel Requests"
n7: rectangle label:"Collect Responses"
n8: diamond label:"All Responses Received?"
n9: rectangle label:"Merge and Transform"
n10: rectangle label:"Return Partial with Fallback"
n5.handle(right) -> n6.handle(left) [label="Decompose"]
n6.handle(bottom) -> Services.n11.handle(top) [label="GET /users"]
n6.handle(bottom) -> Services.n12.handle(top) [label="GET /orders"]
n6.handle(bottom) -> Services.n13.handle(top) [label="GET /products"]
n7.handle(right) -> n8.handle(left)
n8.handle(right) -> n9.handle(left) [label="Yes"]
n8.handle(bottom) -> n10.handle(top) [label="Timeout"]
n9.handle(top) -> Client.n3.handle(bottom) [label="Composed JSON"]
n10.handle(top) -> Client.n3.handle(bottom) [label="Partial JSON"]
}
Services { # Microservices
n11: rectangle label:"User Service"
n12: rectangle label:"Order Service"
n13: rectangle label:"Product Service"
n14: rectangle label:"User Response"
n15: rectangle label:"Order Response"
n16: rectangle label:"Product Response"
n11.handle(right) -> n14.handle(left) [label="Query"]
n12.handle(right) -> n15.handle(left) [label="Query"]
n13.handle(right) -> n16.handle(left) [label="Query"]
n14.handle(top) -> Composer.n7.handle(bottom) [label="User Data"]
n15.handle(top) -> Composer.n7.handle(bottom) [label="Order Data"]
n16.handle(top) -> Composer.n7.handle(bottom) [label="Product Data"]
}
Why This Workflow?
When a single UI view requires data from multiple microservices, having the client make multiple API calls increases latency and complexity. The API composition pattern provides a server-side aggregation layer that fans out requests in parallel, collects responses, and returns a single unified result.
How It Works
- Step 1: The client sends a single query request to the API composer service.
- Step 2: The composer parses the query requirements and identifies which services to call.
- Step 3: Parallel requests are fanned out to User, Order, and Product services simultaneously.
- Step 4: Responses are collected with timeout handling for slow services.
- Step 5: If all responses arrive, they are merged into a single composed JSON response.
- Step 6: If some services timeout, a partial response with fallback data is returned.
Alternatives
GraphQL federation provides query-level composition without a custom aggregator. Client-side composition gives more control but increases latency. BFF pattern is similar but client-specific. This template shows the generic API composition approach.
Key Facts
| Template Name | API Composition Pattern Architecture |
| Category | Architecture |
| Steps | 6 workflow steps |
| Format | FlowZap Code (.fz file) |
Related templates
Architecture
A microservices API gateway architecture diagram showing request routing, JWT authentication, rate limiting, service discovery, and response aggregation across distributed backend services. This template models the entry point for all client traffic in a microservices ecosystem, enforcing security policies before requests reach internal services. Ideal for platform engineers designing scalable API infrastructure with centralized cross-cutting concerns.
Architecture
A database-per-service architecture diagram where each microservice owns its dedicated data store, with event-driven synchronization via Kafka for cross-service data consistency. This template demonstrates the core microservices data isolation principle, showing how PostgreSQL and MongoDB coexist in a polyglot persistence strategy. Critical for architects enforcing service autonomy while maintaining eventual consistency.
Architecture
A Backend-for-Frontend architecture diagram with separate BFF layers for web and mobile clients, each optimizing API responses for their specific platform while sharing common backend microservices. This template shows how to avoid one-size-fits-all APIs by tailoring data aggregation and payload optimization per client type. Recommended for teams serving multiple frontend platforms from a shared microservices backend.
Architecture
An event-driven publish-subscribe architecture diagram with Kafka or RabbitMQ message broker, event serialization, topic partitioning, fan-out delivery to multiple consumers, and dead letter queue error handling. This template models the foundational async messaging pattern where producers and consumers are fully decoupled through a message broker. Essential for architects building loosely coupled, scalable event-driven systems.
Architecture
An event-driven choreography architecture diagram where microservices coordinate through events without a central orchestrator, with Order, Payment, Inventory, and Shipping services reacting to each other's domain events. This template models the decentralized coordination pattern where each service knows only its own responsibilities and publishes events for others to consume. Best for teams favoring autonomous services over centralized workflow control.
Architecture
A saga orchestration architecture diagram with a central orchestrator coordinating multi-step distributed transactions across Order, Inventory, and Payment services, with a dedicated compensation chain for rollback on failure. This template models the orchestration-based saga pattern where a single coordinator manages the transaction lifecycle and triggers compensating actions when any step fails. Essential for architects implementing reliable distributed transactions without two-phase commit.