What an API integration actually involves
Connecting two systems is closer to translating between two languages than plugging in a cable. The seven parts of a real integration.
The short answer
An API is the formal way one piece of software lets another read or change its data: a set of documented requests and responses. An integration is code that uses two or more APIs to keep systems in step, for example creating an invoice in the accounting system when an order is placed in the shop. Connecting two systems sounds like plugging in a cable. In practice it is translation between two systems that describe the world differently, plus all the work of making that translation reliable when things go wrong.
There are seven parts to a real integration. A proposal that mentions only the first three will run over.
The seven parts
| Part | What it involves | What goes wrong without it |
|---|---|---|
| 1. Access and permissions | Credentials issued by the owner, scoped to the minimum needed, stored securely | Integrations running on a personal login, or with far more access than they need |
| 2. Data mapping | Deciding how each field in one system corresponds to the other, including formats, required fields and what to do when there is no match | Records created with missing or wrong data, duplicates, silent mismatches |
| 3. Triggers and timing | What starts a run: an event, a schedule, a webhook; and how often | Delays, missed events, or two systems fighting over who is right |
| 4. Error handling | Retries with backoff, queues, dead-letter handling, idempotency so a retry does not create duplicates | Data lost during outages; duplicate invoices after a retry |
| 5. Rate limits and volume | Respecting each API’s limits, batching where allowed | Runs blocked mid-way; partial updates |
| 6. Logging and monitoring | A record of every run and alerts on failures and on unexpected silence | Nobody notices the integration stopped three weeks ago |
| 7. Change management | Handling API version changes, renamed fields, new required values, vendor deprecations | The integration breaks the day a vendor ships an update |
Where the effort goes
- Understanding both sides. Reading the documentation, testing the real responses, discovering the undocumented behaviour. Often a third of the work.
- Mapping and rules. Agreeing with the business what happens in every mismatch: a customer with no email, an order with a product that does not exist in accounting, a refund.
- Building the happy path. The smallest part, and the only one visible in a demo.
- Building the unhappy paths. Retries, queues, idempotency, alerts. The difference between a demo and a system.
- Testing against both vendors’ sandboxes, then a controlled run with real data and someone watching.
- Monitoring and hand-over. Dashboards, alerts routed to a person, and a document that says what the integration does and what to check when it alerts.
What a good proposal for an integration says
It names both APIs and confirms access has been checked. It lists the data mapping rules and the decisions the business must make. It describes error handling, monitoring and who receives alerts. It states what happens when a vendor changes the API and what annual maintenance covers. And it says what is not included, because an integration that “syncs everything” does not exist.
What this means for you
Two systems with APIs can be connected, and the result can be reliable for years. Budget for the seven parts, not just the demo. Insist on scoped access, idempotent steps, monitoring with a named recipient and a little annual maintenance. And when comparing proposals, favour the one that talks about what happens when things go wrong, because that is where integrations live.
Frequently asked questions
Both systems have an API. Why is connecting them not a quick job?
Because the APIs describe two different pictures of the world. One calls it a customer, the other a contact; one has three address fields, the other one; one updates instantly, the other in batches. The integration has to translate between them, handle every case where they disagree, and keep working when either side changes.
What happens when one system is down?
A well-built integration queues the work and retries with increasing delays, logs what it could not do, and alerts someone if the outage lasts. A badly built one drops the data silently, and the two systems drift apart until someone notices the numbers do not match.
How do we keep an integration working over the years?
Monitoring that alerts on failures and on silence, a log of every run, version control for the code, and a check when either vendor announces API changes. Budget a little maintenance each year. An integration is software, and software that is never touched does not stay working.
Sources
- MDN: Introduction to web APIs (accessed 2026-09-11)