Web Service Broker Pattern

Web Service Broker shields the application core from the awkward details of partner APIs, transport protocols, and external service failure models.

Why This Topic Matters

Why it matters in enterprise Java

Payments, shipping quotes, tax engines, and notification platforms are all external to the core order domain. Their protocol details should not leak into application services or business objects.

Pattern Essentials

Intent, problem, and solution

Intent

What the pattern is trying to achieve

Encapsulate invocation, transformation, and error handling for external web services behind an internal boundary.

Problem

What goes wrong without it

External API details, retry semantics, and transport exceptions leak into the core application design.

Solution

How the pattern answers the problem

Introduce a broker or gateway that translates between external protocols and internal contracts.

Modern Relevance

Why it still matters now

This pattern is extremely relevant in API-driven systems, partner integrations, and anti-corruption layers.

Structure

How the collaboration works

Application code calls the broker through an internal contract.
Broker handles protocol translation, mapping, and failure translation.
External response models stay at the integration edge.
The core receives a domain-appropriate result.

Java Example

Java example in the Order Management domain

Java example: shipping broker over an external HTTP client

package org.javaomnibus.ecommerce.integration;

public final class ShippingBroker {
    private final ShippingHttpClient shippingHttpClient;

    public ShippingBroker(ShippingHttpClient shippingHttpClient) {
        this.shippingHttpClient = shippingHttpClient;
    }

    public ShipmentQuote quote(ShipmentRequest request) {
        ExternalQuoteResponse response = shippingHttpClient.quote(request);
        return new ShipmentQuote(response.total(), response.estimatedDays());
    }
}

Code Walkthrough

Step by step

The broker protects the rest of the application from external response shapes.
Protocol-specific concerns stay localized at the integration boundary.
Internal code receives a cleaner, application-appropriate contract.
This makes later client replacement or fallback behavior easier to contain.

Real-World Usage

Where this pattern shows up

Payment, shipping, tax, and partner API integrations
Gateway layers in monoliths and microservices
Anti-corruption boundaries around external platforms

When Not To Use

Cases where another shape is better

Direct in-process collaborations that are not real integration boundaries
Cases where the broker becomes only a renamed HTTP client with no mapping or shielding value

Trade-Offs

Trade-offs and design pressure

A broker adds a layer, but that layer often pays for itself by containing volatility and protocol leakage.
It must still stay focused on translation and resilience, not absorb domain orchestration.

Comparison Note

How this differs from nearby patterns

Web Service Broker is the integration-edge counterpart to Business Delegate. Both shield callers, but the broker focuses on external service protocol boundaries.

Common Misuse

Mistakes to avoid

Putting business workflow decisions into the broker
Leaking external DTOs upward instead of returning internal contracts
Using the broker as a generic place for all integration code with no clear ownership

Related concepts

Business Delegate Service Activator J2EE vs Spring pattern mapping