Cross-Service Queries & API Composition

That receptionist is exactly what's called the API composition pattern: one component — often called a composer, and sometimes built directly into an API gateway — receives a single incoming request, calls each of the individual microservices that owns a piece of the needed data, waits for all of their responses, and combines them into one response sent back to the client.

The flow looks like this: a client sends one request to the composer. The composer fans that single request out into several independent calls — one to each service that owns a relevant piece of data. Each of those services responds with just its own slice: Customer Service returns the profile, Accounts Service returns the balances, Cards Service returns the card list, Loans Service returns the loan list. The composer waits until every one of those calls has returned, merges the pieces into a single combined object, and sends that back as one response. The client only ever sees one request and one response — the fan-out and merge happen entirely inside the composer.

This pattern deliberately keeps each service completely unaware of the others. Customer Service has no idea Accounts Service even exists; it just answers questions about customers. All of the cross-service knowledge lives in exactly one place — the composer — which keeps every individual service simple and focused on the reality that it owns.

This is also the same underlying idea behind a "backend for frontend": a composer built specifically to shape data for one particular client or screen, rather than trying to be a generic combiner for every possible use case.

Here's what a composed customer-profile endpoint looks like in a Spring Boot service, using the reactive WebClient to call all four services.

The key detail is Mono.zip: it fires all four requests at essentially the same instant, rather than calling Customer, waiting for it to fully finish, then calling Accounts, and so on. If each service takes roughly 100 milliseconds to respond, a sequential approach costs you close to 400 milliseconds in total; the concurrent approach shown in the code costs you close to 100 milliseconds — the time of the single slowest call, not the sum of all four. On a screen where a customer is actively waiting, that difference is the difference between a page that feels instant and one that feels sluggish.

@RestController
public class CustomerProfileController {

    private final WebClient webClient;

    public CustomerProfileController(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.build();
    }

    @GetMapping("/profile/{customerId}")
    public Mono<CustomerProfileResponse> getProfile(@PathVariable String customerId) {

        Mono<CustomerResponse> customer = webClient.get()
            .uri("http://customer-service/customers/{id}", customerId)
            .retrieve()
            .bodyToMono(CustomerResponse.class);

        Mono<List<AccountResponse>> accounts = webClient.get()
            .uri("http://accounts-service/accounts?customerId={id}", customerId)
            .retrieve()
            .bodyToFlux(AccountResponse.class)
            .collectList();

        Mono<List<CardResponse>> cards = webClient.get()
            .uri("http://cards-service/cards?customerId={id}", customerId)
            .retrieve()
            .bodyToFlux(CardResponse.class)
            .collectList();

        Mono<List<LoanResponse>> loans = webClient.get()
            .uri("http://loans-service/loans?customerId={id}", customerId)
            .retrieve()
            .bodyToFlux(LoanResponse.class)
            .collectList();

        // all four calls fire concurrently -- total wait time is the SLOWEST call, not the sum of all four
        return Mono.zip(customer, accounts, cards, loans)
            .map(tuple -> new CustomerProfileResponse(
                tuple.getT1(), tuple.getT2(), tuple.getT3(), tuple.getT4()));
    }
}

Sorting or filtering a combined result across all four services' data is one of the sharpest limits: you can't ask a database to sort data it never had in the first place, so any sorting or filtering that spans services has to happen in application code, after every response has already arrived, which is slow and memory-hungry once result sets grow.

The composer's total response time is also permanently capped by its slowest single dependency, no matter how well the concurrent calls are written. If Loans Service is having a bad day and takes three seconds to respond, every combined profile request now takes at least three seconds too, even though Customer, Accounts, and Cards all answered instantly.

Partial failure is the third honest problem: if one of the four services is temporarily unreachable, the composer has to decide what an incomplete response even means. Do you return the three pieces you have with a placeholder for the fourth? Do you fail the whole request? Neither answer is obviously correct, and the right one usually depends on the specific screen.

These exact limits are the honest reason a fundamentally different pattern exists for situations where composition alone genuinely isn't enough — one that stops fetching and merging data on every single request, and instead keeps a ready-to-read copy sitting there in advance.