API integration · 8 min read
An API integration checklist: what to settle before connecting two systems
A practical checklist for planning an API integration between business systems: data ownership, authentication, failures and retries, monitoring and long-term upkeep.
By Bakaya Partners ·
Connecting two systems looks simple on a whiteboard: an arrow from one box to another. In practice, the arrow hides a dozen decisions about who owns the data, what happens when something fails and who finds out. Integrations that skip those decisions tend to work for a few weeks and then fail quietly. This checklist covers what we like to settle first.
1. Say what the integration is for
Write one sentence: "When X happens in system A, Y should happen in system B, within Z minutes." That sentence tells you whether you need real-time events or a nightly sync, which is the single biggest driver of cost and complexity. Many integrations that people assume must be instant are perfectly happy with hourly.
2. Decide which system owns each piece of data
When two systems both hold a customer's address, one of them has to be the source of truth. Without that decision, edits collide and data drifts. For each field you sync, name the owner, and decide what happens if the other system changes it. Often the answer is "that edit is overwritten", and everyone should know that in advance.
3. Look at what the API actually offers
Read the documentation of both sides with these questions in mind:
- Does it offer webhooks or events, or must you poll for changes?
- What are the rate limits, and will your volume fit within them?
- How does it handle pagination, large exports and bulk updates?
- Is there a sandbox for testing, or only production?
- Is the API versioned, and how much notice is given before changes?
If a system has no API, there may still be options, such as file exports, a database connection or a vendor-supported connector. Each has different trade-offs for reliability and support.
4. Plan authentication and permissions
Use the narrowest access that does the job. Prefer scoped tokens or OAuth over a shared administrator login, store secrets in a proper secrets manager rather than in code, and decide who rotates them and when. Also consider what happens when the person who set up the connection leaves. An integration that runs under one employee's personal account is a failure waiting for a resignation.
5. Design for failure
Networks drop, services go down and APIs return errors. A reliable integration assumes this from the start:
- Retry failed calls with increasing delays, and stop after a sensible limit
- Make operations safe to repeat, so a retry never creates a duplicate order or invoice
- Queue work so a slow or unavailable system does not block everything else
- Set aside messages that keep failing, so a person can inspect them instead of losing them
The idea behind the second point is called idempotency, and it is the difference between a harmless retry and a customer charged twice.
6. Decide how you will know it is working
The worst integration failures are silent. Nothing crashes, the data just stops flowing, and someone notices a month later when the numbers do not add up. Decide up front:
- What counts as healthy: records synced, delay, error rate
- Who is alerted when it is not, and through which channel
- Where logs live, and how long they are kept
- How you will reconcile the two systems periodically to catch drift
7. Test with realistic data
Integrations tend to break on the cases nobody imagined: names with unusual characters, empty fields, very large records, duplicate entries and values in unexpected formats. Test against a copy of real data (anonymised if needed), not a handful of tidy examples. Rehearse the failure cases too: turn one side off and see what happens.
8. Plan for the long run
An integration is not finished when it ships. APIs change, vendors retire versions and your own data evolves. Write down who owns it, where the documentation lives, and how changes will be tested. If you can, put the connection in version control and make it deployable like any other piece of software. And before building custom code at all, ask honestly whether an existing integration platform or the vendors' own connector would do the job. Custom work earns its place when you need the reliability, volume or control that off-the-shelf options cannot give you.
A short checklist
- One sentence describing the trigger, the action and the acceptable delay
- A named source of truth for every synced field
- Documentation read for webhooks, limits, versioning and sandbox
- Narrow, rotated credentials not tied to one person
- Retries, safe repeats and a place for failed messages
- Alerts, logs and a periodic reconciliation
- Tests with realistic and awkward data
- An owner and a plan for change
If you are connecting a CRM, billing system, data warehouse or internal tool and want it done properly, our API and systems integration service can help. Or tell us what you are connecting and we will say honestly what we would recommend.