API integration An API integration needs clear ownership, safe access, retries and proof that records still match.
On a whiteboard, an integration is a line between two boxes. The line is the easy part. The real project must decide which record wins, who is allowed to send a change and what staff see when either system rejects it.
A business owner does not need to design the protocol. They do need written answers about responsibility, data and failure. Use this checklist during scoping, acceptance and handover.
Name the systems and record owners
Write the source and destination for every object. A customer may originate on the website, while invoice status originates in the accounting system. If both systems can edit the same phone number, define precedence and how conflicts are shown.
Identify the business owner, technical owner and vendor contact for each service. Record who controls the subscription and developer account. An integration should not depend on credentials held only in a departed contractor’s personal account.
List the minimum data movement
Create a field map with source name, destination name, format, purpose and sensitivity. Remove fields that the receiving process does not use. Decide whether historical records are included or only new changes after launch.
Mark identifiers separately from display names. A customer called “Green Street Bakery” can be renamed. its stable system identifier should still link the correct record. Write rules for missing values, time zones, currencies and duplicate contacts.
Choose controlled access
Prefer a supported authorisation method such as OAuth 2.0 when the provider offers it. Give the connection only the scopes required for its task. Separate production credentials from development access and store secrets on the server, not in browser code or shared documents.
The GOV.UK API technical standards are written for government services. However, their controls are useful questions for other projects. They recommend HTTPS, authorisation for each request, limited access, monitoring and avoiding basic authentication.
Design for limits and rejection
Providers use rate limiting to protect their services. The integration should slow down, queue work or retry according to the documented response. Repeatedly hammering a limited endpoint can turn a short delay into a wider outage.
Define permanent failures separately. An invalid postcode will not improve after ten retries. Put the record in a visible exception queue with the rejected value, reason and safe correction route.
Prevent duplicates and unsafe repetition
Network timeouts create uncertainty: the destination may have completed a request even though the sender missed the response. Use the provider’s idempotency or stable request key where available. Test repeated delivery so one payment, client or project is not created twice.
Check authorisation at the object level as well as the endpoint. The OWASP API Security Project highlights broken object-level authorisation as a central risk. A valid user must not gain access to another customer’s record simply by changing an identifier.
Use a realistic sandbox
A sandbox should reproduce formats, validation and status changes without containing live personal or payment data. Include awkward cases: non-ASCII names, missing company names, refunded payments, expired tokens and delayed webhooks.
Where a vendor’s test environment behaves differently from production, record the gap and run a controlled live verification. Define the test amount or disposable record, approver and clean-up step before starting.
Agree observable acceptance tests
- A valid new record reaches the correct destination once.
- An update changes the intended record rather than creating another.
- A rejected field appears in an exception queue staff can use.
- A revoked credential produces an alert without exposing the secret.
- A rate limit delays work without losing it.
- Logs identify a transaction without storing unnecessary personal data.
- Recovery catches up safely after one system is unavailable.
Plan ownership after launch
Document token rotation, provider version changes, monitoring, support hours and how to pause the connection. Set a retention period for logs and failed payloads. A successful launch does not remove the need for somebody to investigate tomorrow’s first exception.
Where an integration failed its acceptance test
A wholesaler integrates its ordering system with a courier’s booking API. The acceptance test is written as an observable statement: an order marked dispatched produces a tracking number visible to the customer within five minutes, or an alert to operations.
In the sandbox everything passes. In production, 6% of bookings fail. The courier rate-limits to 100 calls a minute and the wholesaler’s nightly batch fires 400 in under thirty seconds. The API returns 429, the code treats every non-200 as fatal and drops the order.
The fix is small: respect the retry-after header and queue. The point is that the failure showed up as a specific, countable breach of a written test rather than as customers ringing to ask where their parcels were. Nobody had to argue about whether the integration was "working".
Sources and further reading
- GOV.UK API technical and data standards — a public-sector standard used here for access, transport, testing, versioning and monitoring controls.
- OWASP API Security Project — the primary project reference for common API security risks and current testing concerns.
Our business software service can scope the integration around the records, exceptions and operating team rather than treating the API call as the whole project.
Quick API integration action plan
- Name the source of truth. Write down the result. Name one owner.
- List each field that will move. Test this step. Keep proof of the test.
- Keep keys off public pages. Use real data. Check each fact.
- Check request and rate limits. Ask one user. Note what feels hard.
- Use safe retry rules. Fix each fault. Run the check again.
- Block duplicate event work. Set a due date. Review the result.
- Log status with a reference. Write down the result. Name one owner.
- Reconcile both systems often. Test this step. Keep proof of the test.
- Choose one clear goal. Use real data. Check each fact.
- Name the owner for each task. Ask one user. Note what feels hard.
- Test the full path before launch. Fix each fault. Run the check again.
- Set the next review date. Set a due date. Review the result.
- Keep the plan where staff can find it. Write down the result. Name one owner.
- Use plain words in each note. Test this step. Keep proof of the test.
- Save proof for each key check. Use real data. Check each fact.
- Fix one issue at a time. Ask one user. Note what feels hard.
- Check the result with a real user. Fix each fault. Run the check again.
- Remove work that does not help the goal. Set a due date. Review the result.
- Share each major change with the team. Write down the result. Name one owner.
- Run the same checks after each update. Test this step. Keep proof of the test.
- Check the source of every key fact. Use real data. Check each fact.
- Keep private data out of public notes. Ask one user. Note what feels hard.
- Plan what to do when a check fails. Fix each fault. Run the check again.
- Give each choice a clear reason. Set a due date. Review the result.
- Keep old files until new work is proven. Write down the result. Name one owner.
- Ask for help when the risk is high. Test this step. Keep proof of the test.
- Check phone and desktop views. Use real data. Check each fact.
- Make the next step easy to find. Ask one user. Note what feels hard.
- Track the result that matters most. Fix each fault. Run the check again.
- Close each task when proof is saved. Set a due date. Review the result.
Use this API integration plan as a live check. Keep the notes short. Review the work after each major change.
