API: a defined way for software to work together

Think of an agreed service counter

A helpful analogy is a service counter with a clear list of requests it accepts. You can ask for something on that list, provide the required details, and receive a response. You do not need to know every internal step used to produce the response. An API provides that kind of defined boundary for software.

The analogy has limits: an API is governed by precise technical rules rather than a person interpreting an ambiguous request. That is why a business requirement needs to be translated carefully into the actual actions the interface supports.

An API is not the whole integration

Having an API means a system offers a particular interface. It does not mean every other application can immediately work with it. Data integration also requires decisions about which information moves, what it means, and where it belongs. A connector may provide a prepared bridge, while a custom connection requires implementation work.

Ask whether the API supports your exact task rather than whether an API exists at all. Reading a contact record, creating a booking, and changing a booking may be separate capabilities. A positive answer about one does not establish that the others are available in the required way.

An illustrative training business

Imagine a fictional training provider that wants confirmed course registrations to appear in its CRM. The booking service offers an interface for retrieving registrations, and the CRM offers one for creating contacts. The team still needs to define when a registration counts as confirmed, how an existing contact is recognised, and what happens after a cancellation.

Without these decisions, the connection might create duplicate people or leave outdated attendance information. The example shows the practical role of an API: it enables specific exchanges, while the organisation remains responsible for deciding which exchanges are correct and useful for its work.

An integration card for the technical handover

A small requirements analysis becomes tangible when you hand over a task card. The following requirements belong to the fictional training provider. Ask the technical owner to confirm which interface function supports each requirement and which decisions remain open. An arrow connecting two systems does not provide that mapping.

When information changes, establish which source takes precedence. A manually corrected address should not be overwritten by an older value merely because another registration is transferred.

• Trigger: a course registration becomes confirmed. Source: booking system. Destination: CRM.
• Required data: agreed customer identifier, course identifier and registration status. Transfer deadline: [business requirement].
• Existing contact: match through [confirmed identifier]; do not create another contact for every transfer.
• Cancellation: update the affected registration status; do not delete the customer record merely because one registration ends.
• Failed transfer: [responsible role] receives [alert] and checks the actual destination state before another write attempt.
• Test evidence: one confirmed registration on the correct contact, followed by a correctly recorded cancellation. Keep secrets and real customer data off this card.

Access should match the purpose

APIs often require credentials or another method of identifying the calling system. The available permissions determine what that system can read or change. Discuss access appropriate to the connection, ownership of the credentials, and how they can be replaced or withdrawn. Do not place secret credentials in public pages or ordinary shared notes.

Also decide what happens when the responsible employee or supplier changes. A connection that relies on an undocumented personal account can fail unexpectedly or retain access longer than intended. These are manageable operational questions, but they should be answered before the connection becomes part of a daily essential process.

For a REST API, the service must check access for the specific operation on the affected data. Recognising an identity does not permit every change. Ask to see both the required actions and those that should be denied.

Retries must not create a second booking

Connected systems can be unavailable, limit requests or return incomplete responses. One important case is a booking that was saved but whose confirmation never reached the sender. The sending system does not know the outcome. Creating the booking again could produce a duplicate.

A connection must not blindly repeat HTTP writes. For non-idempotent methods, RFC 9110 describes automatic retries only under additional conditions, such as knowing that the implementation preserves the intended effect or detecting that the original request was not applied. Have the technical owner confirm this property for the particular API.

Require a defined retry path, an alert after unsuccessful attempts and a responsible person. Automation becomes dependable when someone can recognise and resolve an uncertain outcome. In an approved test, check “saved, but no response” as well as a completely unavailable service.

Test a representative small connection

A limited proof of concept can check feasibility before a large commitment. Use suitable sample data and include more than the perfect case. Test an existing customer, missing information, a changed booking, and an interrupted request.

Verify the result in the receiving application, not only the message returned by the connection. Confirm that the right person can identify and correct a failed transfer. A demonstration proves only what it actually tested. Record remaining assumptions, especially around scale, permissions, and information updates, so the team does not mistake a narrow experiment for a fully operational service.

Keep an owner after the first successful exchange

Interfaces can evolve, credentials can expire, and the business process can change. Someone needs to monitor the connection, understand provider notices, and maintain the mapping between systems. Keep a short record of its purpose, supported actions, responsible people, and recovery procedure. Review it when either application changes significantly.

A successful first transfer is a beginning, not proof that the integration will run indefinitely without care. The practical measure of quality is whether the connection continues to deliver correct information, exposes problems clearly, and can be adjusted by someone other than the person who originally built it.