Architecture

Use the Adapter Pattern to Isolate External Services

Translate external provider APIs into stable application contracts so vendor changes do not spread through the codebase.

External services change their APIs, error formats, authentication methods, and availability. An adapter protects the rest of the application from those details.

Define the application-facing port

Describe what the application needs in its own language, such as send notification, charge payment, or retrieve a document. Do not copy a vendor's request and response objects into the domain model.

Translate at the boundary

The adapter maps application requests to provider calls and translates responses, exceptions, and status codes back into application-level outcomes. Keep provider SDK usage inside the adapter.

Handle failure explicitly

Define timeouts, retryable errors, idempotency behavior, and fallback policy. Do not retry every failure: validation errors and rejected credentials usually require different handling from temporary network errors.

Test without the provider

Use contract tests and controlled fakes to verify mapping and failure behavior. Add integration tests against a sandbox or provider test environment where available.

Checklist

  • Define a provider-independent application contract.
  • Keep SDK types inside the adapter.
  • Translate errors into meaningful outcomes.
  • Set timeouts and safe retry policies.
  • Test mappings and provider failure modes.
Share this page Help other developers discover this resource.