API Composition Pattern in Microservices

import java.math.BigDecimal;
import java.util.Map;

public class OrderDetailsComposer {

    // Data owned by three different services
    record Order(String orderId, String customerId, String shipmentId, BigDecimal total) {}
    record Customer(String customerId, String name, String city) {}
    record Shipment(String shipmentId, String status, String carrier) {}

    // The composed view the client asked for
    record OrderDetails(String orderId, String customerName, String city,
                        BigDecimal total, String shipmentStatus, String carrier) {}

    // Stand-ins for the three services (in a real system: HTTP calls)
    static final Map<String, Order> orderService = Map.of(
            "ORD-1001", new Order("ORD-1001", "C-42", "SHP-77", new BigDecimal("1499.00")));
    static final Map<String, Customer> customerService = Map.of(
            "C-42", new Customer("C-42", "Asha Rao", "Pune"));
    static final Map<String, Shipment> shipmentService = Map.of(
            "SHP-77", new Shipment("SHP-77", "OUT_FOR_DELIVERY", "SwiftShip"));

    static OrderDetails compose(String orderId) {
        Order order = orderService.get(orderId);                       // 1. needed first: it holds the other ids
        Customer customer = customerService.get(order.customerId());   // 2. uses order.customerId()
        Shipment shipment = shipmentService.get(order.shipmentId());   // 3. uses order.shipmentId()

        // 4. join the three results in memory
        return new OrderDetails(order.orderId(), customer.name(), customer.city(),
                order.total(), shipment.status(), shipment.carrier());
    }

    public static void main(String[] args) {
        OrderDetails details = compose("ORD-1001");
        System.out.println(details);
    }
}

OrderDetails[orderId=ORD-1001, customerName=Asha Rao, city=Pune, total=1499.00, shipmentStatus=OUT_FOR_DELIVERY, carrier=SwiftShip]

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

public class ParallelComposer {

    record CustomerSummary(String name, int loyaltyPoints) {}
    record ProfilePage(String name, int loyaltyPoints, String recommendations) {}

    static void pause(long millis) {
        try {
            Thread.sleep(millis);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    // Three independent services with different response times
    static String customerName() { pause(150); return "Asha Rao"; }
    static int loyaltyPoints() { pause(200); return 320; }
    static String recommendations() { pause(5_000); return "Mechanical Keyboard"; } // this one hangs

    public static void main(String[] args) {
        // Java 21: one cheap virtual thread per remote call
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            long start = System.nanoTime();

            CompletableFuture<String> name = CompletableFuture.supplyAsync(ParallelComposer::customerName, executor);
            CompletableFuture<Integer> points = CompletableFuture.supplyAsync(ParallelComposer::loyaltyPoints, executor);
            CompletableFuture<String> recs = CompletableFuture.supplyAsync(ParallelComposer::recommendations, executor)
                    .completeOnTimeout("(recommendations unavailable)", 300, TimeUnit.MILLISECONDS); // optional data: fallback

            ProfilePage page = name
                    .thenCombine(points, (n, p) -> new CustomerSummary(n, p))
                    .thenCombine(recs, (summary, r) -> new ProfilePage(summary.name(), summary.loyaltyPoints(), r))
                    .join();

            long elapsedMillis = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);
            System.out.println(page);
            // Sequential calls would take 150 + 200 + 5000 ms; in parallel we wait only until the 300 ms timeout
            System.out.println("Waited for the timeout, not the sum of all calls: "
                    + (elapsedMillis >= 300 && elapsedMillis < 1_000));
            executor.shutdownNow(); // stop the hung recommendations call instead of waiting for it
        }
    }
}

ProfilePage[name=Asha Rao, loyaltyPoints=320, recommendations=(recommendations unavailable)]
Waited for the timeout, not the sum of all calls: true

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;

public class OrderHistoryComposer {

    record Order(String orderId, String productId) {}
    record OrderRow(String orderId, String productName) {}

    static int remoteCalls = 0;   // counts simulated network round trips

    static final List<Order> orders = List.of(
            new Order("ORD-1", "P-10"), new Order("ORD-2", "P-20"),
            new Order("ORD-3", "P-10"), new Order("ORD-4", "P-30"));
    static final Map<String, String> productCatalog = Map.of(
            "P-10", "Mechanical Keyboard", "P-20", "Wireless Mouse", "P-30", "USB-C Hub");

    static List<Order> fetchOrders() {
        remoteCalls++;
        return orders;
    }

    // One call per product: GET /products/{id}
    static String fetchProductName(String productId) {
        remoteCalls++;
        return productCatalog.get(productId);
    }

    // One call for many products: GET /products?ids=...
    static Map<String, String> fetchProductNames(Set<String> productIds) {
        remoteCalls++;
        return productIds.stream().collect(Collectors.toMap(id -> id, productCatalog::get));
    }

    static List<OrderRow> naive() {
        List<OrderRow> rows = new ArrayList<>();
        for (Order order : fetchOrders()) {
            rows.add(new OrderRow(order.orderId(), fetchProductName(order.productId()))); // N extra calls
        }
        return rows;
    }

    static List<OrderRow> batched() {
        List<Order> list = fetchOrders();
        Set<String> ids = list.stream().map(Order::productId).collect(Collectors.toSet());
        Map<String, String> names = fetchProductNames(ids);                               // 1 extra call
        return list.stream().map(o -> new OrderRow(o.orderId(), names.get(o.productId()))).toList();
    }

    public static void main(String[] args) {
        remoteCalls = 0;
        List<OrderRow> rows = naive();
        System.out.println("Naive:   " + remoteCalls + " remote calls");

        remoteCalls = 0;
        List<OrderRow> same = batched();
        System.out.println("Batched: " + remoteCalls + " remote calls");

        System.out.println("Same result: " + rows.equals(same));
        same.forEach(row -> System.out.println("  " + row.orderId() + " -> " + row.productName()));
    }
}

Naive:   5 remote calls
Batched: 2 remote calls
Same result: true
  ORD-1 -> Mechanical Keyboard
  ORD-2 -> Wireless Mouse
  ORD-3 -> Mechanical Keyboard
  ORD-4 -> USB-C Hub