API Composition is the microservices pattern that hides the complexity of “many independent backends” behind a single, unified response to the client.

Imagine you order a pizza online. The app shows you the price, the estimated delivery time, the driver’s name, and your loyalty points — all on one screen. That single screen almost certainly did not come from one place. Behind the scenes, a “pricing service” knows the price, a “logistics service” knows the delivery time, a “driver service” knows the driver’s name, and a “loyalty service” knows your points. Somebody has to go ask each of these services a question and glue the answers together into one neat response. That “someone” is API Composition.

API Composition is a design pattern used mainly in microservices architectures, where a single client request is fulfilled by calling multiple backend services, and then combining (“composing”) their individual responses into one unified result before sending it back to the client.

Where Did This Pattern Come From?

To understand why API Composition exists, we need a tiny bit of history. In the early 2000s, most large applications were built as monoliths — one big codebase, one big database, one deployable unit. If you wanted the price and the delivery time of an order, you simply ran one SQL query that joined a few tables in the same database. Easy.

Around 2011–2014, companies like Netflix, Amazon, and Uber began breaking their monoliths into microservices — small, independently deployable services, each owning its own private database. This solved a lot of problems (teams could move faster, services could scale independently, failures were isolated), but it created a brand new problem: data that used to live in one table now lives in five different databases, owned by five different teams, that cannot be joined with SQL anymore.

API Composition emerged directly as an answer to this gap. It became one of the standard patterns documented in microservices literature (notably popularized by Chris Richardson’s microservices.io pattern catalog) alongside close relatives like the API Gateway pattern and the Backend-for-Frontend (BFF) pattern.

Let’s make the problem concrete with our pizza-delivery example. Composition exists to solve a specific, sharp pain that only appears once you split a monolith into microservices.

In a monolith, getting an order’s full details might be one query:

SELECT o.id, o.price, d.eta, u.name AS driver, l.points
FROM orders o
JOIN delivery d ON d.order_id = o.id
JOIN users u ON u.id = d.driver_id
JOIN loyalty l ON l.user_id = o.user_id
WHERE o.id = 42;

One database, one query, done. But once orders, delivery, users, and loyalty each live inside their own microservice with their own private database, this SQL simply cannot exist anymore — because a database cannot JOIN across a network boundary into someone else’s database. That is the core motivation.

What Problem Does API Composition Actually Solve?

API Composition solves all four by introducing a single component — the composer (often called an “API Composer” or “aggregator”) — that sits between the client and the microservices, does all the fan-out calling and merging work once, and gives the client one clean response.

Before going further, let’s define the vocabulary clearly. These terms recur through every remaining section, so getting them straight now pays off.

Client-Side vs Server-Side Composition

There are two flavors of this pattern, and understanding the difference matters a lot:

Why the Distinction Really Matters

The choice between client-side and server-side composition is not just a stylistic preference — it directly affects how easily you can evolve your microservice architecture. With server-side composition, you can split a service in two next quarter, rename an internal endpoint, or move it to a different region, and no external client ever notices; the composer absorbs the change. With client-side composition, every one of those internal moves risks breaking mobile app builds still in use by customers who have not upgraded, which is why nearly every mature production system converges on the server-side variant as its default posture.

Let’s zoom out and look at where the composer physically sits in a typical microservices architecture.

Notice the composer sits behind the API Gateway (sometimes the composer is logic embedded inside the gateway itself, sometimes it is a standalone service). Let’s break down each piece.

Where Composition Logic Physically Lives

Let’s trace exactly what happens, technically, when a composed request arrives — from the client’s single HTTP call to the merged JSON response coming back.

Java Example: A Simple Parallel Composer

Here is a simplified Java example using CompletableFuture to fan out requests in parallel and merge them — this is the heart of how a real-world composer works.

public class OrderSummaryComposer {

    private final OrderServiceClient orderClient;
    private final DeliveryServiceClient deliveryClient;
    private final DriverServiceClient driverClient;
    private final LoyaltyServiceClient loyaltyClient;

    public OrderSummary getOrderSummary(String orderId) {

        // 1. Fan-out: fire all calls in parallel, non-blocking
        CompletableFuture<Order> orderFuture =
            CompletableFuture.supplyAsync(() -> orderClient.getOrder(orderId));

        CompletableFuture<Delivery> deliveryFuture =
            CompletableFuture.supplyAsync(() -> deliveryClient.getDelivery(orderId));

        // Driver depends on delivery.getDriverId(), so it chains after delivery
        CompletableFuture<Driver> driverFuture = deliveryFuture.thenCompose(delivery ->
            CompletableFuture.supplyAsync(() -> driverClient.getDriver(delivery.getDriverId())));

        // Loyalty is "best effort" — allowed to fail without breaking the response
        CompletableFuture<Loyalty> loyaltyFuture =
            CompletableFuture.supplyAsync(() -> loyaltyClient.getPoints(orderId))
                .exceptionally(ex -> Loyalty.unavailable()); // fallback on failure

        // 2. Gather: wait for everything, with an overall timeout
        CompletableFuture.allOf(orderFuture, deliveryFuture, driverFuture, loyaltyFuture)
                .orTimeout(2, TimeUnit.SECONDS)
                .join();

        // 3. Merge into one composite response
        return new OrderSummary(
            orderFuture.join(),
            deliveryFuture.join(),
            driverFuture.join(),
            loyaltyFuture.join()
        );
    }
}

Dependency-Aware Fan-out

Notice one subtle detail in the code above: the Driver call does not run in the very first batch, because it needs the driver ID that only comes back inside the Delivery response. Real composers frequently have this shape — a mix of independent calls that can go in parallel from the start, plus one or two “dependent” calls that must chain after an earlier response. A well-written composer is really a small directed acyclic graph of calls, where every branch that can run in parallel does, and only the truly dependent hops wait for their upstream input.

Let’s visualize the full lifecycle of a single composed request, including the tricky bit: what happens when one service fails while the others succeed.

Notice that even though the Loyalty service failed, the overall request still succeeds — this is a deliberate design decision called graceful degradation, and it is one of the most important lifecycle behaviors of a well-built composer.

The Lifecycle of a Composite Field

1. Request mapping — the composer decides which downstream calls the incoming request requires.
2. Dispatch — calls go out, typically via HTTP/REST, gRPC, or message queues.
3. Timeout & retry — each call has its own timeout budget and possibly a retry policy.
4. Response validation — the composer checks each response is well-formed before using it.
5. Merge / transform — fields are renamed, reshaped, or computed (e.g., converting cents to dollars) to match the client’s expected contract.
6. Caching decision — the composer may cache the composite result for a short TTL to save future calls.
7. Response delivery — the final JSON (or GraphQL) payload is returned to the client.

API Composition is a high-leverage pattern, but it introduces its own operational surface area. Here is what you gain and what you pay.

Key Trade-offs to Think About

Because a composed request depends on multiple downstream calls, performance needs deliberate engineering — it does not happen by accident.

The Golden Rule: Parallelize Independent Calls

As shown earlier, calls that do not depend on each other’s results should always run concurrently. Calls that do depend on a previous result (like needing the delivery record before you can look up the driver) must be chained, but everything else should fan out at once.

Timeout Budgets

A composer should set an overall deadline for the whole composite request (say, 2 seconds), and divide that budget sensibly across the calls it makes, rather than letting any single slow provider eat the whole budget.

Scaling the Composer

• Stateless design — composers should hold no session state, so you can run many identical instances behind a load balancer.
• Connection pooling — reuse HTTP connections to downstream services instead of opening new ones per request.
• Async I/O — non-blocking frameworks (like reactive Java with WebFlux, or Node.js) let one instance handle thousands of in-flight composite requests without needing a thread per request.
• Caching — cache frequently requested, slow-changing composite results (e.g., product catalog data) to avoid unnecessary fan-out entirely.

Batching and Coalescing Requests

A subtler performance technique is request coalescing: if the composer receives many concurrent requests that all need the same downstream data (for example, hundreds of users viewing the same popular product page in the same second), a well-tuned composer can consolidate them into a single downstream fetch and share the result across every waiting request, rather than firing one identical downstream call per incoming user request. Combined with a small in-memory cache, this can turn a thundering herd of duplicate downstream calls into one, which is enormously helpful at scale.

Because composition introduces more moving parts (and more network calls) than a single database query, reliability has to be designed in explicitly.

Circuit Breakers

A circuit breaker is like an electrical fuse: if a provider service starts failing repeatedly, the circuit breaker “trips” and the composer stops calling it for a while (returning a fast fallback instead), giving the struggling service room to recover instead of being bombarded further.

Bulkheads

A bulkhead (borrowed from ship design, where separate watertight compartments stop one flooded section from sinking the whole ship) isolates resources per downstream call — for example, using a separate thread pool for calls to the Loyalty service, so if Loyalty gets slow, it cannot exhaust the threads needed to call Order and Delivery.

Retries with Backoff

Transient failures (a brief network blip) can be retried, but retries must use exponential backoff with jitter — waiting slightly longer between each retry, with some randomness — to avoid a “retry storm” where every client retries at exactly the same moment and overwhelms an already-struggling service.

The composer sits in a privileged position — it talks to many internal services on behalf of the client — so it needs careful security treatment.

• Authentication propagation — the composer typically validates the client’s token (e.g., a JWT) once at the gateway, then forwards a trusted internal token or context to downstream services, rather than making every provider re-validate the raw client credential.
• Least privilege — each provider service should only expose the fields the composer actually needs, not entire internal records.
• Field-level authorization — the composer must be careful not to accidentally merge sensitive fields (like another user’s data) into a response just because a downstream call returned them.
• mTLS between services — mutual TLS ensures the composer and provider services trust each other’s identity on the internal network.
• Rate limiting — since one client request can fan out into several backend calls, a small client-side attack can amplify into a much larger load on internal services; rate limiting at the gateway protects against this.

Amplification and Abuse

Because a composite endpoint quietly turns one incoming request into several backend calls, it also silently amplifies whatever load hits it. That is fine for legitimate traffic, but it is also an attractive target for someone trying to abuse the system: a request that costs an attacker 1 ms of network effort can trigger 5 or 10 backend calls, each with its own database query. Composers therefore usually pair per-user rate limits at the gateway with per-dependency circuit breakers, so a burst of malicious traffic cannot silently become a burst of expensive downstream work.

Because a single client request now touches several services, observability has to be able to answer: “which downstream call made this request slow or broken?”

Distributed Tracing

Each incoming request is tagged with a unique trace ID that is passed along to every downstream call. Tools like Jaeger, Zipkin, or OpenTelemetry let you visualize the entire fan-out as one connected trace, showing exactly how long each provider call took — making it trivial to spot which particular hop is dragging down the composite latency for a given request.

Structured Logging

Logs from the composer should include the trace ID, the target service, response time, and status for every downstream call — this makes it possible to reconstruct exactly what happened for any given failed or slow request after the fact.

Alerting on the Right Things

A subtle but important observability lesson for composers: alert on per-dependency SLOs rather than only on the aggregate composite endpoint’s SLO. A composite endpoint may still meet its overall latency target while one specific dependency is quietly degrading enough to cause partial failures on a growing fraction of requests. Separate per-dependency dashboards and alerts catch that class of slow-motion incident well before the aggregate metric would ever look bad enough to page someone.

API Composers are typically deployed the same way as any other microservice: as containerized applications (Docker) orchestrated by Kubernetes, often sitting right behind a managed API Gateway.

Rolling Out Changes Safely

Because the composer depends on the contracts of multiple provider services, deployments should use canary releases or blue-green deployments, along with contract testing (e.g., Pact) to catch breaking changes in provider APIs before they reach production.

Multi-Region Considerations

For globally distributed applications, deploying composers close to their users (in multiple regions) dramatically reduces perceived latency — but it also means each regional composer instance needs local, low-latency access to its downstream services (or fast read replicas thereof), because a composer in Singapore calling providers only in Virginia will still be as slow as any other cross-region round trip. Regional composers therefore typically pair with regional deployments (or at least regional caches) of the provider services they call most.

Composition sits carefully above the data layer: it talks only to service APIs, never to their databases directly. Here is how that plays out end-to-end.

Databases

A defining feature of the microservices world that necessitates composition is the database-per-service pattern — each provider service owns its own database (SQL or NoSQL) and never lets another service query it directly. The composer never touches a database directly; it only talks to service APIs.

Caching

Caching is one of the most effective performance levers for a composer:

• Per-provider caching — cache individual downstream responses (e.g., product details that rarely change) to skip redundant calls.
• Composite response caching — cache the fully merged result for a short TTL (e.g., 30 seconds) when slight staleness is acceptable.
• Cache invalidation — providers can publish change events (via a message broker) that tell the cache layer to invalidate stale composite data.

Load Balancing

Both the client-to-composer hop and the composer-to-provider hops need load balancing:

API Composition is deeply tied to how microservices expose their APIs. Let’s look at how it plays with the common API styles.

API Composition vs. API Gateway vs. BFF — What’s the Difference?

API Composition rarely lives in isolation — it lines up next to a handful of closely related patterns, and it has its own set of recognizable anti-patterns.

Related Design Patterns

Anti-patterns to Avoid

A distilled checklist of the practices that make composers pleasant to operate — and the mistakes that quietly turn them into pager-driven nightmares.

A Sensible Rollout Path for a New Composite Endpoint

You have almost certainly interacted with API Composition already today — you just did not see it. Here are some places where it hides in plain sight.

Across all of these, the underlying motivation is identical to our pizza-delivery example: independently owned, independently scaled services, with a composition layer that gives the end user (or the mobile client) one fast, unified answer — regardless of how many separate teams and databases actually contributed to it behind the scenes.

A quick round of the questions that get asked most often when a team is deciding whether — or how — to introduce API Composition.

Is API Composition the same as an API Gateway?

No, but they are closely related. An API Gateway is the single entry point for all client traffic and can host many responsibilities (auth, rate limiting, routing). API Composition is a specific pattern — often implemented inside the gateway, or as a separate service behind it — for combining data from multiple backend services into one response.

Does API Composition replace a shared database?

Not exactly — it is a workaround for not having one. In a monolith with a single database, you would use SQL joins. In microservices, each service owns its data privately, so composition is how you reconstruct a “joined” view across service boundaries at request time.

Is GraphQL the same thing as API Composition?

GraphQL (especially with schema federation) is one popular implementation approach for composition — it lets you declare a unified schema across services and have a gateway resolve fields from the right subgraph automatically. But you can absolutely do API Composition with plain REST and hand-written merging code too.

What happens if one of the services is down?

A well-designed composer applies fallback logic: critical data may cause the whole request to fail, while non-critical data is simply omitted or marked unavailable so the rest of the response still succeeds — this is called graceful degradation.

When should I NOT use API Composition?

If your application is still a monolith with one shared database, you do not need this pattern — a normal query is simpler and faster. It is specifically valuable once you have split into microservices with separate databases and a client needs data that spans more than one of them.

Can composition happen for writes, not just reads?

Composition is primarily a read-side pattern. Coordinating writes across multiple services is a different, harder problem usually solved with the Saga pattern instead.

How is composition different from caching a joined view up front?

Materialized views (a common alternative under the CQRS umbrella) pre-compute the joined data ahead of time and store it in its own read store, so requests read it directly without any real-time fan-out. That is often faster at read time, but it introduces its own operational cost: keeping the materialized view fresh as source data changes. Composition trades that up-front cost for a small per-request fan-out cost. Many production systems end up using both — a materialized view for the hottest, cheapest-to-precompute reads, and live composition for everything else.

API Composition is the pattern that lets a microservices architecture feel simple from the outside, even though it is complex on the inside.

It solves the very real problem created by splitting a monolith’s shared database into many independently owned databases: related data ends up scattered, and something has to put it back together for the client. That “something” is the composer — a thin, deliberately narrow layer whose whole job is fan-out and merge.

Once you see this pattern, you will notice it everywhere — nearly every modern app screen you use is quietly the product of an API Composer working behind the scenes, gathering pieces from independent teams and independent databases into the single, unified answer you actually see.