How to integrate systems through an API: contracts, statuses and recovery
Integrating systems through an API enables data exchange and operations through defined interfaces. The work is complete when every value’s source, each operation’s status and recovery after failures can be explained. This guide prepares a verifiable connection between two systems, with a small example and criteria for accepting delivery.
By the end, you can:
- Specify inputs, outputs and statuses
- Distinguish events from full synchronisation
- Test repeated events, access and recovery
Choose the authoritative source for each field
Describe the journey in business terms: “an order confirmed in the sales system creates a job in the operational system”. Identify the common reference and data direction. If both systems can change the same date, decide which takes precedence and how conflicts reach review.
Map by field, rather than just by application. The sales system may own the order and the operational system its execution status. Avoid generic two-way synchronisation that sends every change back to its origin. Define which changes matter and when the current status must be queried.
| Example field | Authoritative source | Destination |
|---|---|---|
| order_id | Sales system | External job reference |
| service_code | Approved catalogue | Job type |
| requested_date | Confirmed request | Preference, subject to planning |
| work_status | Operational system | Progress information |
Write the contract before connecting credentials
Record operations, fields, types, permitted values, responses and errors. OpenAPI defines a way to describe HTTP interfaces for people and tools. If the supplier provides that description, check the version and examples; otherwise document the connection’s minimum contract. Documentation does not replace testing the real operation.
Define what absent, empty and null mean. An omitted property may mean “do not change”, while null may mean “clear”, depending on the API. Also specify date formats, units, limits and calculated fields. These decisions prevent synchronisation deleting information merely because one system did not send it.
Use a fictional request with an expected result
In the example, order ORD-104 is confirmed and should create a job. The event has its own identifier and an order revision. The requested date is a preference, rather than an automatic reservation. The names and format below are a teaching proposal; they must be adapted to the APIs actually contracted.
Expected processing validates the event, looks up the external reference, creates or updates the permitted draft and saves the job identifier. Repeating the same event should return the recorded result. A later revision may change authorised fields; an old revision arriving afterwards must not replace the latest state.
{
"entrada": {
"schema_version": 1,
"event_id": "evt-demo-104-3",
"event_type": "order.confirmed",
"order": {
"order_id": "ORD-104",
"revision": 3,
"service_code": "MANUTENCAO",
"requested_date": "2026-11-25"
}
},
"resultado": {
"event_id": "evt-demo-104-3",
"processing_status": "completed",
"work_id": "TRAB-208",
"work_status": "draft"
}
}Authorise the operation and the specific record
Keep credentials in the server component and grant only the necessary operations. Separate test and production environments and define how to rotate credentials without losing control of the connection. Technical logs should support investigation by reference without copying secrets or excessive personal data.
Authentication identifies who makes the request; authorisation decides whether they may act on that record. OWASP highlights the need to check object access when an API receives its identifier. Test a reference belonging to another fictional account: a valid credential should not consequently expose every record.
Combine events with a way to check the complete set
A webhook reports an event; a query obtains data according to the API contract. Verify notification authenticity using the supplier’s mechanism before trusting the content. Stripe documents signature verification, repeated deliveries and no guarantee of delivery order, for example. Confirm your supplier’s behaviour instead of assuming it is the same.
Periodic reconciliation compares references and statuses to find differences left by a lost event. When querying lists, follow pagination: the first response may contain only some records, as GitHub documentation shows. Record the cursor or continuation point and handle changes during reading according to the API’s guarantees.
Distinguish a temporary failure from an invalid request
An interrupted connection may leave the result uncertain: the destination may have saved before the response was lost. Use the provided reference and idempotency mechanism, checking scope and expiry. Stripe documents this mechanism; that does not mean every API accepts the same key or offers the same guarantees.
Limit attempts, respect the supplier’s waiting instructions and send persistent failures for review. A queue may deliver a message again, as in the at-least-once delivery model documented by Cloudflare. Consumers therefore also need to recognise repeats. An invalid field is not corrected by indefinitely repeating the same request.
Approve statuses and recovery using concrete evidence
In acceptance testing, confirm ORD-104 generates a single TRAB-208 even after repetition, and that completed refers to integration processing while draft refers to the job. These are statuses of different entities. Then simulate a failure, resume and compare records on both sides.
Include an old version, an out-of-order event, a usage limit, a revoked credential and a multipage list. Assign responsibility for alerts and contract changes. When an API announces deprecation, its update must repeat these tests before replacing the connection the team uses.
| Test | Acceptance evidence |
|---|---|
| Same event twice | One business operation and a reused result |
| Lost response | Reconciliation finds the result without duplication |
| Earlier revision arrives later | Current state preserved according to policy |
| Several data pages | All expected references checked |
| Access to another account | Operation rejected without changing data |
Worksheet for your project
Business journey and expected result: Systems, environments and responsible people: Fields and authoritative source for each: Contract, version, input, output and errors: Common reference, event and revision: Permissions and technical-log retention: Event authenticity: Pagination, continuation and reconciliation: Idempotency, attempts and persistent failures: Processing and business statuses: Test cases and evidence from both sides: Alerts, maintenance and recovery procedure:
Sources and criteria
Content prepared with AI assistance and research using technical sources, with checks of the relevant examples and calculations. The references support the guide’s decisions; examples identified as fictitious let you try out the method.
