An API integration is often described as 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, but 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.
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.
Xapner’s business software service can scope the integration around the records, exceptions and operating team rather than treating the API call as the whole project.