← Technical notes

Illustrative

Based on patterns I've built in production (details under NDA). The example domain below is illustrative.

One interface for many third-party APIs

Example domain: a shipping platform integrating several courier APIs, each with different auth, payload formats and status names.

The problem

Every provider signs requests differently, names statuses differently, and some report an intermediate processing state before the final result.

How it works

  1. A single internal interface (create, query, parse callback) and a registry. Adding a provider means one adapter plus one registration.
  2. On boot, each active account is loaded with its credentials; a broken account is skipped and reported instead of crashing the service, and credentials are never logged.
  3. Each adapter verifies the callback signature and maps provider statuses to internal ones, including an explicit pending flag.
  4. Pending events are acknowledged but do not change state; only final events do.
  5. Every outbound call is written to an audit log on a best-effort basis, so logging failures never change the business result.
  6. Test tenants short-circuit to mock responses and never call the real API.
Loading diagrams…