API integration checklist: beyond the happy path.
A reliable integration defines the source of truth, validates access and data, handles retries without duplicating work and exposes failures to an operator. A successful test request proves only one part of the flow.
Use the free worksheetTest what happens after the first success.
Illustrative example: an external order event should create one fulfilment task. The task must still be correct when events repeat or a dependency fails. These are proposed acceptance checks, not delivery guarantees shared by every API provider.
| Test input | Required business result | Evidence to inspect |
|---|---|---|
| Same event, twice | One fulfilment task for the same business operation. | Match the operation identifier to one resulting task. |
| Same event, concurrently | Concurrent workers must not both create the task. | Exercise the overlap. A sequential duplicate test is insufficient. |
| Older event arrives last | An older event must not overwrite a newer authoritative state. | Compare the stored state with the provider's ordering or version contract. |
| Timeout after remote success | Reconcile the completed operation before attempting to create it again. | Look up the operation using the agreed stable identifier. |
| Access expires | Expose a recoverable failure to the operator. | Renew access in the test environment and verify controlled replay. |
Choose who owns each piece of data.
If a customer changes an address in two systems, which value wins? If an order is deleted, should the integration delete the corresponding record elsewhere? These are product decisions, not details to leave to the connector.
Map the fields and the direction of updates. Record identifiers used to match records across systems. A display name or email address may change, so it is not automatically a suitable permanent identifier.
Check access before promising the integration.
Read the documentation for the actual provider, plan and API version. Confirm the operations available, authentication method, account permissions and test environment. An API existing does not mean the required account can use every endpoint.
Credentials should have the access the integration needs and a documented renewal path. Store them outside the source repository. Define what an operator sees if credentials expire or access is revoked.
Assume an event may arrive again.
Providers can retry event delivery. Stripe's webhook documentation, for example, describes retries, duplicate events and a lack of guaranteed event ordering. Check your provider's contract rather than assuming every event arrives once and in sequence.
Make the business operation safe to retry. Track the provider's event or operation identifier and the result already produced. If an earlier attempt timed out, inspect what happened before issuing the same action again.
Distinguish temporary failure from invalid work.
A temporary service outage may justify a later attempt. A malformed address or revoked permission usually needs a different response. Repeating every failed request indefinitely can make a bad state harder to recover.
Define timeouts, provider limits and the point where an operator takes over. Keep diagnostic information useful enough to resolve the issue, while avoiding credentials and unnecessary personal data in logs.
Test the operational result.
Use representative scenarios: duplicate delivery, a late event, a provider outage and a manual change in the destination system. Check the resulting records, not just the HTTP status returned by the connector.
For an order integration, a useful acceptance test might show that replaying the same paid event leaves one order and one fulfilment request. Then rehearse how a failed event is inspected and retried. That turns recovery into a supported workflow.
The checklist.
- Source of truth and field mapping agreed.
- Actual account access and API version checked.
- Duplicate and out-of-order events considered.
- Retries cannot casually repeat the business action.
- Provider limits and credential renewal documented.
- An operator can inspect and recover failed work.
Take it into the project.
API integration test worksheet.
Map a business operation across systems, then write the tests for duplicates, ordering, failures and recovery.
Download the worksheet (.txt)Plain text, ready to edit. No account or email required.
Preview the worksheet questions
- Business operation
- Describe the trigger, systems involved and completed result. Name the operator who owns the flow.
- Source of truth
- For each field, record authoritative system, stable identifier, update direction and deletion behaviour.
- Provider contract
- Record provider, API version, account plan, permissions, limits, event guarantees and test environment. Link to the documentation checked.
- Authentication and renewal
- Record the credential owner, required scopes, renewal process and expected behaviour after expiry. Do not include credentials.
- Duplicate and ordering tests
- Deliver an event twice, deliver duplicates concurrently and deliver events in reverse order. State the expected business state after each.
- Ambiguous timeout test
- Simulate an external operation completing before your client times out. How will the system reconcile it without creating duplicate work?
- Failure and replay
- Define retry limits, invalid records, failure visibility and a controlled replay process. State the evidence that replay is safe.
- Release evidence
- Record environment, operation IDs, observed outcomes, unresolved cases and the person accepting the integration.
Sources.
Technical references checked on .