How to plan an API integration before development
A discovery checklist for connecting a product to another service, including ownership, failure modes, permissions, data mapping, and ongoing cost.
By Aleksej Djokic ยท
An integration is a dependency, not a checkbox
Before development, establish what data moves, who owns it, when it must be current, and what the product should do when the other system is unavailable. A successful demo only proves that two systems can talk once; a production integration must behave predictably across retries, changes, limits, and partial failure.
Document the contract
Name the source of truth
For each field, decide which system owns creation, updates, deletion, and display. Define how conflicts are resolved.
Map identity and permissions
Describe how accounts match, what scopes are required, and what happens when access is revoked or a user leaves.
Design failure behavior
Set timeout, retry, duplicate-prevention, rate-limit, and user-facing error rules. Never retry a non-idempotent action blindly.
Plan observability and change
Record safe correlation details, monitor failures, test against realistic responses, and identify who receives provider-change notices.
Questions to answer early
- Does the provider support webhooks or only polling?
- Are sandbox data and production data shaped the same way?
- What are the retention, privacy, and deletion obligations?
- What happens if the provider changes pricing, scopes, or API versions?
- Is a manual recovery path available for an incomplete sync?
The limitation
You cannot make an external provider more reliable than it is. A good integration contains that uncertainty with queues, clear status, safe retries, and a human recovery path rather than pretending the dependency is local.