Software engineering / Integrations
The integration is only as good as its handoffs
Questions to ask before connecting two systems, from data ownership to retries and operational visibility.
Hamza Afzal ·
Connecting two APIs is only one part of an integration. The difficult questions often appear around the handoff: which system owns a record, what happens when a request fails, and how someone knows the work is complete.
Choose the source of truth
For each shared field, identify the system that owns it. If two platforms can update the same value, decide how conflicts will be resolved before they happen.
Document the mapping in plain language alongside the technical field names. That makes the behavior reviewable by the people who depend on it.
Define failure behavior early
A timeout does not always mean an operation failed. The remote system may have accepted the request even if the response never arrived.
Consider how duplicate work is detected, which errors are safe to retry, and which ones need a person to intervene. Where the remote API supports an idempotency mechanism, use it deliberately and preserve its identifiers.
Make the state understandable
An integration should tell its operators what is pending, complete, or blocked. A technical log helps a developer investigate; a clear status helps the business keep working.
Useful operational context includes the related record, the last attempt, and the next action. Avoid putting secrets or unnecessary personal information in logs.
Plan for change
Credentials expire, schemas evolve, and business rules change. Include configuration, documentation, and ownership in the handover.
The result should be a connection someone can operate and maintain, with a clear understanding of its limits.