API integration: joining two systems without creating a third problem

An API integration is code that makes two systems exchange data — orders into an accounting package, contacts into a mailing tool, invoices out of a shop. The first version usually works within a day, which is exactly why integrations are underestimated: the build is short and the ownership is permanent.

The useful question before writing anything is what happens when the other side is unavailable, slow, or different from yesterday. An integration that assumes none of those ever happen works perfectly until the first time one does, and then fails in the least convenient way — silently, mid-transfer, with half the records moved.

Decisions to make before the first request

• Direction and authority. Which system owns each field, and what happens when both change it. Without an answer, you have built a loop that overwrites work.
• Trigger. On an event, on a schedule, or on demand. Events are faster; schedules are easier to reason about and recover.
• Volume and rate limits. Read the documented limits before designing, not after being throttled in production.
• Identity. How a record on one side is matched to the other. An external id stored on both sides beats matching on email or name, which will eventually match the wrong thing.
• Failure policy. Retry, skip, or stop and alert — decided per error type rather than uniformly.

Practices that keep it working

1. Retry with exponential backoff, and respect any retry-after header. Hammering a struggling service turns a blip into an outage.
2. Make writes idempotent, using an idempotency key where the API supports one. Network failures leave you genuinely unsure whether the write landed.
3. Log every request and response, with secrets redacted. Integrations fail in the space between two systems and neither side's logs alone will tell you why.
4. Store the last successful sync point, so that recovery resumes rather than restarts.
5. Alert on silence as well as on errors. An integration that has transferred nothing for two days is usually broken, and nothing in the error log will say so.
6. Pin the API version where the provider offers one, and read their changelog. Undocumented changes on the other side are the most common cause of a working integration failing.

The most expensive integrations are the invisible ones. A sync that fails loudly gets fixed in an hour; a sync that quietly stops moving records is discovered weeks later, when somebody notices a gap in the accounts. Monitor for absence of activity, not just for errors — it is a five-line check and it catches the failure mode that actually costs money.

Build, buy, or avoid

Three honest options. Writing it yourself gives full control and permanent ownership, which is right when the logic is specific to your business. An integration platform costs a subscription and handles retries, logging and connectors — usually the better deal for standard connections between well-known products. And the third option, genuinely underused: not integrating. A weekly CSV export that somebody imports in five minutes is unglamorous and has no on-call burden, and for low volumes it beats both alternatives.

Where Ettex fits

Ettex API is the interface into Ettex data, with event delivery covered in webhook. The authentication side of connecting systems is discussed in single sign on.

To be clear: we are not an integration platform. There is no connector marketplace, no visual workflow builder and no managed sync service. What we provide is a documented API and webhooks; the integration is yours to build or to buy elsewhere.