An API integration requirements document must let a developer implement the exchange and a process owner verify the result. “Transfer customers, products and orders” is not sufficient: it leaves the source, trigger, required fields, update rules, error response and completion criteria undefined.
A useful specification starts with business events. Describe what happened and what outcome both systems need, then define objects, mappings, identifiers, call sequence, retries, security, monitoring and acceptance scenarios.
Start with the boundary and required outcome
State the goal in one paragraph without technical decoration. For example: “When an online order is confirmed, create it in fulfilment, reserve available stock and return a confirmed identifier and state. Send dispatch and cancellation changes back to the store.”
List exclusions beside the goal: historical orders, accounting documents, catalogue cleansing or reverse product editing. An explicit boundary protects the first release from endless expansion.
| Section | Question answered | Verifiable outcome |
|---|---|---|
| Goal and scope | Which process is connected | Release boundary is clear |
| Objects and owners | Where authoritative data is created | No conflicting edits |
| Events and sequence | When and in what order data moves | Flow is reproducible |
| Errors and retries | How the flow recovers | No duplicates or silent loss |
| Monitoring | Who sees an exception | Every issue has an owner |
| Acceptance | How readiness is proved | Tests have unambiguous results |
Register objects and master systems
For customer, product, price, stock, order, payment and state, name the authoritative system. If both systems may edit a field, specify conflict resolution. “Two-way synchronisation” without that rule creates update loops and accidental overwrites.
Every object needs internal and external identifiers. Email, phone or product name cannot be the only key because they change and can repeat. Store identifier mappings explicitly.
Describe fields together with behaviour
A field table needs more than name and type. Include required status, source, allowed values, transformation, empty-value behaviour and a non-personal example.
| Field | Rule | Error or edge case |
|---|---|---|
| external_id | Stable unique source key | A repeat updates the same object |
| status | Mapped through an approved state table | Unknown value enters exception review |
| amount | Sent with currency and rounding rule | Mismatch blocks financial confirmation |
| updated_at | Change time with timezone | Old event cannot overwrite newer state |
| warehouse_id | Reference to warehouse mapping | Unknown location requires configuration |
Define events and order
For each scenario, document trigger, preconditions, request, expected response and follow-up. “Order changed” is too broad: changing a comment, address and order lines has different consequences after picking begins.
- The source records the business event in its own transaction.
- The event enters a durable exchange queue.
- The receiver validates identifier and data version.
- The operation is performed once and returns an explicit result.
- The source marks delivery or schedules a retry.
- Reconciliation detects rare omissions.
Specify retry behaviour before failure occurs
The network may fail after an operation completes but before the response arrives. Repeating the request must therefore be safe. The client sends an idempotency key or stable operation identifier, and the server returns the previous result instead of creating a duplicate.
Separate temporary and business errors. Timeout or service unavailability can be retried automatically. Unknown product, closed warehouse or forbidden state transition requires data correction or operator action; infinite retries add noise.
Turn logs into operational monitoring
Technical logs help developers, but the business needs an exception queue containing object, operation, reason, attempt count, next retry and owner. Critical events need deadlines. A confirmed order, for example, should not remain without a reservation result beyond the agreed interval.
| Acceptance scenario | Expected result | What it proves |
|---|---|---|
| Normal creation | Object created and identifiers linked | Primary path |
| Repeat same request | No duplicate; original result returned | Idempotency |
| Receiver unavailable | Event retained and delivered after recovery | Queue durability |
| Invalid field | Clear error and assigned exception | Data governance |
| Events arrive out of order | Old state does not overwrite new state | Version control |
| Reconciliation | Deliberately omitted object is found | Detection of silent loss |
Security and operation
Specify authentication, minimum permissions, secret storage, transport encryption, rate limits, masking of personal data in logs and key rotation. Production credentials do not belong in the document or examples.
Also name system owners, incident contacts, acceptable downtime, pause and restart procedures, API version and compatibility policy. These details determine whether the integration remains supportable after launch.
Final review
- goal is stated as a business outcome;
- scope and exclusions are explicit;
- every object has a master source;
- identifier and mapping rules are defined;
- events have triggers and preconditions;
- retries cannot create duplicates;
- errors are separated by handling method;
- monitoring shows the affected object and owner;
- acceptance includes negative scenarios;
- security and operating rules are agreed.
The specification is ready when it supports both implementation and proof of correctness during normal operation and failures. For integrations around Business Reactor Core, this contract preserves a consistent model for orders, states and responsibility across connected systems.
