Structuring integration code.
WHAT THE PROBLEM IS
Calls to external services scattered through an application.
WHAT THAT CAUSES
Authentication handled several ways Inconsistent error handling No single place to add retries or logging Impossible to replace a provider
WHAT TO BUILD INSTEAD
One client per external service, used everywhere.
WHAT IT SHOULD HANDLE
Authentication and token refresh Retries and backoff Timeouts Translating errors into your own types Logging
WHY TRANSLATING ERRORS MATTERS
The rest of the application should not know the provider's error codes.
WHAT TO DEFINE
An interface describing what you need, not what the provider offers.
WHY
It lets you replace the provider without touching the application.
WHAT TO KEEP OUT OF THE CLIENT
Business logic.
WHAT TO PUT IN A LAYER ABOVE
Decisions about what to do with results.
WHAT TO MAKE CONFIGURABLE
Addresses, credentials, timeouts and limits.
WHY
They differ per environment, and hard-coding them guarantees an incident.
WHAT TO ADD
A way to disable an integration quickly.
WHY
When a provider misbehaves, turning it off is the fastest remedy.
WHAT TO TEST
The client, against a controlled substitute.
