Planning a system integration: what should you clarify before API development?
An API is only the technical connection. A dependable integration also needs data ownership, stable identifiers, failure handling, access control, and monitoring.
AT A GLANCE
Before integrating systems, define which system owns each field, what triggers a transfer, how the same business record is identified on both sides, and what happens after a failure or repeated request. Only then should you choose endpoints and technology. Acceptance testing should cover duplicates, missing data, permission errors, and temporary outages as well as the normal path.
- Give every field a named source of truth.
- A repeated request must not create an unnoticed duplicate.
- Failures need a visible state, an owner, and a safe reprocessing path.
Describe the business event before the system boundary
Do not begin with “we need an API”. Choose one complete event, such as sending an approved order to an invoicing service. Document its trigger, required information, where the decision is made, and which state proves completion. If the workflow cannot be explained clearly, a list of endpoints will not resolve unclear responsibility.
Separate genuine real-time needs from convenience. Some events must move immediately; for other data, a controlled scheduled transfer may be simpler and safer. The right pattern depends on acceptable delay, recovery requirements, and the consequence of a missing or twice-processed event.
Name the data owner and stable identifier
For every transferred field, state which system is authoritative, who may change it, and when it must be refreshed. A name or email address alone is rarely a stable business identifier. Use a persistent internal identifier and document how identifiers map across systems. Include merge, deletion, and reopened-record scenarios.
Create a field map covering data type, requirement, allowed values, and sensitivity. Transfer only personal data needed for the defined purpose. Data minimisation is not a later clean-up task; it belongs in the interface contract and the preparation of test data.
Make the interface contract testable
Document operations, inputs, responses, error codes, and versioning. An OpenAPI description can help developers and tests work from the same contract, but the file does not replace business rules. State when a status becomes final and which fields may change later.
Limit access to what the connection needs. Use separate credentials for test and production, keep secrets out of source code and logs, and make access revocable. Changes need a compatibility decision and notification process; an unannounced field rename can stop an operational workflow.
Design retries and failure paths
After a connection failure, the caller may not know whether the other system applied the request. Automatic retry is safe only when the operation is idempotent by design or through a unique operation key. The IETF HTTP standard distinguishes retries of idempotent and non-idempotent requests; blindly repeating an apparently failed POST can create duplicates.
Define timeouts, backoff, retry limits, and the point at which a case enters human review. A failure record should contain the operation identifier, time, state, and next action without unnecessarily copying the full sensitive payload. Prefer a visible, repairable state to silent data loss.
Test the full story and hand over an operable connection
Acceptance tests should cover the normal case, a missing required field, a repeated event, expired access, provider rate limits, and a temporary outage. Check how consistency is restored after partial success. Use anonymised or synthetic test data and define success for every case in advance.
Production needs monitoring, alert thresholds, a named owner, and a rollback path. Handover includes the field map, interface description, access register, failure-reprocessing procedure, and ownership of future changes. In line with the NIST SSDF, security and remediation belong throughout the lifecycle rather than in a single pre-launch check.
Sources and further reading
- OpenAPI Specification v3.0.4OpenAPI Initiative · Checked: 2026-10-31
- RFC 9110: HTTP Semantics — Idempotent MethodsRFC Editor · Checked: 2026-10-31
- Secure Software Development Framework (SSDF) Version 1.1NIST · Checked: 2026-10-31
- General Data Protection Regulation, Article 5European Union · Checked: 2026-10-31
Related questions
What should be clarified before developing an API integration?
Define the business event, authoritative data source, stable identifiers in both systems, field map, permissions, and the state that proves completion. Then design endpoints, versioning, error responses, and acceptance tests.
How should a system integration handle failures safely?
Give every operation a unique identifier and visible state. Retry automatically only when the operation is idempotent; otherwise first determine whether the change was applied. Use bounded retries, a human review queue, a recorded next action, and a named owner.
Borbély Kristóf
The developer behind Kriside, writing practical guides about web systems, automation, and AI solutions.