API Integration Checklist: What to Decide Before You Connect

Before integrating with an API, decide six things: the data contract, how systems authenticate, what happens when the other side is down, what data each system is allowed to see, how you’ll handle changes to the API, and how you’ll know when the integration breaks. Getting a first successful request is quick. Those six decisions are what make it survive production.

I’ve worked on integrations with KYC providers, open banking, accounting platforms, e-signature, and credit reference agencies. The providers change; these questions don’t. (There’s more on that in my API integrations case study.)

1. Data contract

What information enters and leaves each system?

• Which fields do you send and receive, and which are required?
• Who owns the definition of each field, and where is it written down?
• How are IDs matched between the two systems?
• What formats are used for dates, time zones, currencies, and enumerations?
• What does the API return for missing or unknown values: null, empty string, or nothing at all?
• Is the integration synchronous (request and wait), asynchronous (webhooks, queues), or batch?

2. Authentication and security

How should systems, clients, and providers connect securely?

• What authentication method does the provider use (API keys, OAuth 2.0, mutual TLS)?
• Where are credentials stored, and who can access them?
• How are credentials rotated, and what breaks when they are?
• Are separate credentials used per environment?
• If the provider calls you (webhooks), how do you verify the request really came from them?

3. Reliability and failure handling

What happens when the external service is slow or unavailable?

• What timeouts are set, and what happens when one is hit?
• Which requests are safe to retry, and is there an idempotency key so retries don’t create duplicates?
• Is there a backoff strategy so retries don’t make an outage worse?
• What does the user see while the provider is down?
• Can work be queued and processed later, or does the whole flow stop?
• What are the provider’s rate limits, and what happens when you reach them?

4. Data boundaries

What information should each system be allowed to access?

• Are you sending only the data the provider needs, or everything because it was easier?
• Does any of the data fall under regulation (personal, financial, health)?
• Where does the provider store and process the data?
• How long is data retained on each side, and how is it deleted?
• Is sensitive data kept out of logs?

5. Change and versioning

What happens when the external API changes?

• Is the API versioned, and how much notice does the provider give before breaking changes?
• Who on your side receives those notices?
• Is the provider’s API wrapped in a thin layer of your own, so a change touches one place and not the whole codebase?
• Do you have tests against the provider’s sandbox that would catch a breaking change?

6. Observability

How do you know when an integration fails?

• Are requests, responses, and errors logged with enough context to debug a single transaction?
• Is there an alert when error rates rise, or when expected webhooks stop arriving?
• Can support staff see the status of an integration for a specific customer?
• Is there a way to replay or reconcile failed transactions?

Silent failures are the dangerous ones. An integration that stops sending webhooks without an error can look healthy for days.

Before you sign the contract

Some of these answers depend on the provider, not on you. Ask them before committing:

1. Is there a sandbox that behaves like production?
2. What are the rate limits and uptime commitments?
3. How are breaking changes communicated, and with how much notice?
4. Can you export all your data if you leave?

Integrations are part of your architecture, not plumbing to sort out at the end. If you’re designing several of them at once, that’s squarely solution architecture work, and something I help with.