How to plan an API integration for a business website

An API integration should be planned around the business information it moves and the failures it must handle. Before a developer connects two systems, define which data is exchanged, who owns it, how access is granted and what users should see when the connection is unavailable.

Describe the job in one sentence

For example: 'When a customer books an appointment, create the booking in the staff system and send a confirmation only after the staff system accepts it.' This is more useful than 'integrate the website with the diary'. It defines the trigger, the data destination and the order of events.

List the fields to be sent and received. Decide which system is the source of truth if a value changes in both places. Check whether the data includes personal information and whether the business needs every field. The ICO's data protection by design guidance supports limiting data use to what is necessary from the outset.

Confirm access and technical boundaries

Ask the supplier for current API documentation, test credentials, authentication method and any usage limits. Find out whether it can notify your website of changes or whether your site must request updates. Check who can create and rotate credentials and where they are stored.

If the API exposes records by identifier, permissions need attention. A user should not gain access to another person's booking merely by changing an ID. OWASP's API security guidance highlights object-level authorisation as a common risk. Put the required access checks in the specification and test them.

Plan for a service that sometimes fails

What should happen if the external system is slow, rejects a record or accepts it but the website loses the response? Decide whether to retry, queue for staff review or show a clear message to the user. Avoid creating duplicate orders or confirmations when a request is repeated.

Set a practical reconciliation process. Staff should be able to see which records succeeded, failed or need attention without reading raw technical logs. Ask how long errors are retained and who receives alerts.

Test the complete journey

Use a safe test environment and cases for valid data, missing fields, permission failures, timeouts and duplicate submissions. Confirm what happens when either system changes its API. Agree who updates the integration and how much notice the external supplier provides.

An integration is ready when its success and failure paths are clear to users and operators, not merely when a test request returns a positive response.

Frequently asked questions

Do we need real customer data to test an API?

Usually not. Use test accounts and safe sample data where possible, while checking that formats and permissions match the live arrangement.

Who should own the API credentials?

The organisation should control the supplier account and grant appropriate access to the developer. Keep credentials in a protected configuration, not in public code.

What if the other system has no test environment?

Agree a controlled test plan, limits and rollback with its owner. Record which behaviours remain unverified before putting the integration into live use.