Provider Integration Gateway

Overview

A Spring Boot service acting as a unified gateway for a heterogeneous set of third-party provider APIs. Each provider had different authentication schemes, data models, protocols, and reliability profiles. The gateway normalized all of them behind a single internal API, exposing a consistent interface to upstream services.

Problem

The platform was integrating with 8+ tour operator APIs. Each had been integrated individually by different engineers at different times. The result was eight different HTTP clients, eight different retry strategies, eight different data normalization layers spread across the main application.

When a provider changed their authentication scheme, you had to find the right file, understand its particular approach, and update it without breaking the others. When a provider went down, the main application had no circuit breaker and cascaded failures.

Architecture

The gateway introduces a strict separation between the abstract provider contract and the concrete implementations:

ProviderPort (interface)
    ↑ implemented by
ConcreteProviderAdapters (one per provider)
    ↑ wrapped by
ProviderRegistry (selects adapter by provider key)
    ↑ called by
GatewayService (applies cross-cutting concerns)
    ↑ exposed through
REST API (consumed by upstream services)

Cross-cutting concerns — retry, circuit breaking, caching, logging, rate limiting — are applied in GatewayService once, not per adapter.

Key design decisions

Resilience4j for circuit breakers. Each provider gets an independent circuit breaker configuration. A degraded provider trips its own circuit without affecting the others. Half-open state probes recovery automatically.

Redis for availability caching. Provider availability data is expensive to fetch and doesn’t change by the second. Cache with configurable TTL per provider (based on their documented refresh frequency). A background job warms the cache on a schedule to reduce cold-miss latency.

Structured logging with correlation IDs. Every outbound request and inbound response is logged with a trace ID that ties together the upstream call, the provider call, and any errors. Debugging a provider integration issue takes minutes, not hours.

Contract tests per adapter. Each provider adapter has a contract test suite that runs against a recorded fixture of the real provider’s responses. When a provider changes their schema, the test fails before it reaches production.

Operational lessons

The most valuable feature wasn’t technical — it was the admin dashboard showing per-provider health, latency percentiles, circuit breaker state, and cache hit rates. When the platform team reported availability issues, the dashboard made it immediately obvious whether the cause was upstream logic or a specific provider.

Visibility into the integration layer is as important as the integration logic itself.