Building API Integrations That Actually Last

Why Integration Projects Fail

API integration projects have a higher failure rate than most other software projects, and the failure mode is distinctive: they work on delivery, then break six months later when something upstream changes. The root cause is almost always the same — the integration was built to the current state of both systems, with no consideration for the fact that either system might change. An integration built to connect System A and System B assumes System A and System B will always behave the way they do right now. They will not.

The problem is compounded by the fact that integrations are often treated as lower-priority work — "plumbing" — and are therefore under-resourced, under-documented, and under-monitored. When they break, the failure is usually discovered through a user reporting missing data or a downstream process that silently stopped working days earlier. InfoQ's writing on API versioning practices covers some of the upstream versioning strategies that reduce this risk.

The Architecture Decisions That Matter

Three decisions, made early, determine most of the long-term maintainability of an integration:

1. Synchronous vs. asynchronous. A synchronous integration calls the external system and waits for a response. It is simple to implement and easy to reason about. It is also fragile — if the external system is slow or unavailable, the calling system is blocked. Asynchronous integrations use a message queue or event stream to decouple the two systems. They are more complex to implement but significantly more resilient. For any integration that handles more than a few requests per minute, asynchronous is almost always the right choice.

2. Schema ownership. Which system's data model is authoritative? When the two systems have different representations of the same entity — a "client" in one system is a "customer" in another — there must be a clear rule about which representation is canonical and how conflicts are resolved. The absence of this decision is the source of most data consistency problems in integrations.

3. Event sourcing vs. state polling. State polling — asking "what is the current state?" on a schedule — is the path of least resistance and the source of most race conditions. Event sourcing — responding to "something changed" notifications — is harder to implement but produces integrations that are both more accurate and more efficient.

Authentication and Security

Service-to-service authentication is one of the most commonly botched parts of integration projects. Short-lived tokens are treated as permanent credentials. API keys are stored in code rather than environment variables. Webhook payloads are accepted without signature verification. Each of these shortcuts is a security vulnerability that is also a maintainability problem — when the credentials change, everything that used them incorrectly breaks.

The standard we apply: every external credential lives in the environment, never in code. Every inbound webhook is verified against a signature or shared secret. OAuth tokens are refreshed before they expire, never after. These are not exotic requirements — they are table stakes for any integration that handles business data.

Error Handling and Resilience

External systems fail. Networks time out. APIs return unexpected status codes. An integration that does not handle these cases gracefully is not an integration — it is a connection that works when the external system cooperates. Proper error handling means: exponential back-off for retries, idempotency keys to prevent duplicate operations on retry, dead-letter queues for messages that cannot be processed, and explicit handling of partial success states.

Observability and Alerting

An integration that runs invisibly until it fails is a liability. Every integration we build at Exclolab includes structured logging of every request and response, alerting on error rate thresholds, and a health-check endpoint that upstream systems can poll. When something breaks, the failure is detected in minutes — not discovered by a user a day later.