API integration design: how do you connect systems reliably?
Reliable integration is more than moving data between two APIs. Data ownership, state mapping, idempotency, retry and reconciliation determine whether connected systems stay consistent over time.
Define data ownership before data flow
Integration projects often begin by deciding which endpoint to call. The more important question is which system owns which truth. If a customer, payment, reservation or content record can change independently in two systems, synchronization problems eventually become operational problems.
A healthier contract defines ownership before transport. An external product can remain authoritative for its specialist capability while the application's domain model owns the relationships and operational states needed by the business.
Map external states into the domain explicitly
Two products rarely use identical states, identifiers and lifecycle rules. Copying a provider's state directly into an internal model allows the provider's vocabulary and assumptions to leak into the application's business rules.
A mapping layer makes that translation explicit. It can define how external states map to internal states, what happens when an unknown value arrives and how identifiers are related across systems. That contract can then be tested independently from transport code.
- External and internal identifier mapping
- State and enum translation
- Required and optional field boundaries
- Unknown or newly introduced state behavior
- Version and backward-compatibility decisions
Retry and idempotency belong together
Networks fail, providers return temporary errors and sometimes the remote operation succeeds even though its response never reaches the caller. Retry is therefore a normal integration concern. But if repeating a request can create a second payment, reservation or record, retry becomes a new failure mode.
Idempotent operations make the same intent safe to resend. A unique operation key, external reference or controlled upsert can tie retry behavior to the domain action instead of treating it as a transport-only concern.
Failures need visibility and reconciliation
Leaving an integration failure as a log line makes it difficult for operations to understand what actually happened. The system should make it possible to determine which operation failed, when it was last attempted, what the external system returned and whether trying again is safe.
Some failures close with automatic retry; others require a mapping, permission or configuration decision. Reconciliation rereads the current state on both sides and helps answer whether the operation truly failed or only its response was lost.