How to plan an integration between systems
A guide to defining an integration: outcome, source of truth, APIs, data mapping, errors, security and operations.
Direct answer
To plan an integration, first define the operational outcome and involved systems. Then assign a source of truth for each datum, review APIs and permissions, map fields and states, design authentication, synchronization, retries and error handling, and establish monitoring and ownership. Test realistic cases and decide what happens when one side is unavailable.
Key takeaways
- Define system of record, owner and direction for every data element.
- Design retries, idempotency, reconciliation and manual operations before release.
- Security and observability are part of the integration contract.
Start with the operational outcome
“Connect two systems” does not explain what should change for people. Define the event that begins the flow, the information crossing the boundary and the resulting decision or action.
Also identify volume, frequency and acceptable delay. An overnight report and a validation during access require different designs.
Assign a source of truth
Every important datum needs an owning system. If both sides can modify it without precedence rules, loops and contradictions emerge.
Map identifiers, formats, states and empty values. Semantic differences often cause more failures than technical transport.
Design for errors and security
Review authentication, least-privilege access, secrets and sensitive data. Log enough to diagnose failures without exposing protected content.
Define retries, duplicate handling, limits and messages for API failures. Some errors can recover automatically; others need a queue with a human owner.
Operate and evolve the connection
Monitoring should show whether the flow works and where it stopped. Named ownership prevents an alert from existing without anyone able to act.
APIs and rules change. Document dependencies, versions and regression tests, and prepare a procedure for pausing or reconciling data during a change.
Bynotek analysis
The operating contract missing between two APIs
For each object—customer, payment, membership, order—define identifier, system of record, shared fields, direction, frequency and conflict policy. Bidirectional integration without explicit authority creates loops and overwrites legitimate corrections.
Specify behavior for duplicates, delay, wrong order, rate limits, invalid data and partial outage. OWASP includes unsafe API consumption and improper inventory among relevant risks; document versions, credentials, sensitive data and owners for every connection.
Operate with correlated traces, metrics, alerts and a recoverable case queue. Subscription webhooks illustrate the pattern: events may be asynchronous and repeated; the receiver must verify origin, process idempotently and reconcile state.
Applied example
Example: payment received, access not updated
The payment provider confirms the transaction, but the access system is temporarily offline. The integration preserves the event, retries with an idempotency key, alerts after a threshold and exposes a manual queue. On recovery it reconciles without duplicating validity.
Checklist
- 01System of record per data element
- 02API contract and versioning
- 03Idempotency and retries
- 04Alerts and reconciliation
- 05Manual mode and owner
Comparison summary
| Decision | Example question |
|---|---|
| Purpose | Which action should it enable? |
| Ownership | Which system owns each datum? |
| Synchronization | When and in which direction does it move? |
| Failure | Should it retry, block or be reviewed? |
| Operations | Who monitors and reconciles it? |
Sources and references
- [1]
OWASP
API Security Top 10 ↗A reference for reviewing authorization, authentication, resource consumption, configuration and API inventory.
- [2]
Stripe Docs
Webhooks and the subscription lifecycle ↗A technical example of why payments, renewals, failures and cancellations must be modeled as events and states, not a single date.
- [3]
NIST
Secure Software Development Framework (SSDF) 1.1 ↗A framework for incorporating requirements, design decisions, protection and vulnerability response throughout development.
Related guides
Next step
Evaluate an integration with Engineering →