System integrations & APIs
When people are the integration
Someone exports a file every morning and imports it somewhere else. That is an integration — it is just running on a person, and it fails quietly when they are on leave.
In short
A system integration moves data between two systems that were not designed to talk, so that people stop being the transport layer. Done properly it is not just a connection: it needs a defined contract between the systems, idempotent writes so a retry cannot duplicate an order, reconciliation to prove both sides agree, and a path for the records that fail validation. Most integration projects that disappoint were scoped as the happy path only.
When it applies
Signals this is the work
If more than one of these is true today, the problem is usually further along than it looks from the outside.
A scheduled export exists
A CSV moves between systems on a cadence, maintained by one person who has never taken two consecutive weeks off.
The same data is typed twice
An order, a customer or an invoice is keyed into a second system by hand, and the two disagree often enough that someone checks.
Reporting needs a reconciliation step
Nobody trusts a number until it has been cross-checked against another system.
A product was bought and never connected
The tool does its job in isolation and creates work at both edges.
Errors surface at the customer
You find out about failures when someone complains, not when they happen.
How we do it
The sequence
- 01
Agree the contract
What moves, in which direction, how often, and which system is authoritative when they disagree. Most integration pain is an unresolved answer to that last question.
- 02
Check the data first
Identifiers rarely match across systems as cleanly as anyone expects. The mismatch is found and quantified before build, because it determines the shape of everything after it.
- 03
Make writes idempotent
A retry must not create a second order. This is designed in rather than patched after the first duplicate reaches a customer.
- 04
Design the failure path
What happens when the far end is down, slow, or returns something unexpected. Records that cannot be processed go somewhere a person can see and act on.
- 05
Reconcile continuously
A daily check that both sides agree, with the difference reported. An integration nobody is checking is an integration nobody knows is broken.
- 06
Monitor as a business process
Alerting on throughput and error rate, not just on whether the service is running.
What we will not do
The refusals
- Build a real-time integration where a scheduled batch would be cheaper and easier to reason about.
- Integrate two systems when the honest answer is to retire one of them.
- Ship without reconciliation, because the demo looked correct.
- Hide integration failures from the people who need to act on them.
Questions
Before you ask
Tell us what isn't working.
One process, one system, one decision you are stuck on. We will come back with how we would approach it, what it would take, and whether it needs building at all.