Discovery, automation and integration guidance for businesses building connected software and AI-enabled workflows.
View topic guides01 / GUIDE
A successful API test is not the same thing as a reliable integration
Connecting two endpoints once can be easy. Production integrations must keep working when tokens expire, services slow down, payloads change, duplicate events arrive or one system is temporarily unavailable.
Integration planning is therefore mostly about contracts and failure behaviour rather than the first successful request.
02 / GUIDE
1. Define the business event
Start with what should happen in business terms. For example: “when a paid order is created, create or update the customer in the CRM and record the order reference”. This is clearer than beginning with endpoint names because it defines the outcome that must remain true.
03 / GUIDE
2. Confirm the source of truth
For each important field, decide which system owns the authoritative value. If both systems can overwrite the same data without a rule, synchronisation conflicts are inevitable.
Document identifiers carefully. Email addresses, names and product descriptions are often poor substitutes for stable IDs.
04 / GUIDE
3. Choose the trigger model
Webhooks can provide near-real-time events when the provider supports them reliably. Scheduled polling may be appropriate when webhooks do not exist or when periodic reconciliation is valuable. Some integrations use both: webhooks for speed and scheduled reconciliation for assurance.
05 / GUIDE
4. Design authentication and secret handling
Use the provider-supported authentication method, such as OAuth 2.0, scoped API keys or signed requests. Store credentials outside source code, limit permissions and design for rotation and expiry.
Service accounts should have only the access required by the integration.
06 / GUIDE
5. Define the data contract
Map fields, types, required values, formats and transformations. Decide what happens to unknown, missing or invalid data. If an upstream field changes meaning, the integration should fail visibly rather than silently corrupting downstream records.
07 / GUIDE
6. Build for retries without creating duplicates
Temporary failures are normal. Use sensible timeouts, bounded retries and idempotency or deduplication strategies so retrying a request does not create duplicate orders, invoices, tickets or customer records.
08 / GUIDE
7. Respect rate limits and provider outages
Understand quotas and back-off requirements. Queue work when appropriate instead of hammering a failing API. Decide how long work can wait and when a human needs to be alerted.
09 / GUIDE
8. Log enough to diagnose failure safely
Record correlation IDs, provider responses, attempt status and relevant timing while avoiding unnecessary sensitive data in logs. Operators should be able to answer what happened to a specific transaction without reproducing it manually.
10 / GUIDE
9. Test the bad paths deliberately
Test expired credentials, malformed payloads, duplicates, timeouts, provider 5xx responses, rate limiting and partial downstream failure. The production incident you avoid is usually worth more than the extra happy-path demo.
11 / GUIDE
10. Assign ownership after launch
Every integration needs an owner for credentials, provider changes, monitoring, incident response and future schema updates. If an external API is business-critical, document the dependency and define what the business does when that provider is unavailable.
12 / GUIDE
Integration planning checklist
- Business event and required outcome defined.
- Source systems and systems of record agreed.
- Identifiers and field mappings documented.
- Authentication and secret storage designed.
- Trigger method selected.
- Timeout, retry and idempotency strategy defined.
- Rate limits understood.
- Logging and alerts specified.
- Failure paths tested.
- Support owner and documentation identified.