Imagine an ordering website sends a new order to an operations system. The operations system saves it, but the confirmation never reaches the website. Should the website try again? Could that create a second order? This illustrative situation shows why an API contract matters to business operations. It describes the expected behaviour on both sides, including the cases a successful demonstration may never reveal.
On this page
Start with the business journey and data ownership
Map one interaction from the user’s action to its confirmed outcome. For the order example, identify who creates the order reference, which system decides whether the order is accepted and where the customer checks its status. Distinguish a request received from an order accepted: these may be different events. Also decide which system may change each fact. If both systems can edit a delivery address, the contract needs a rule for handling updates rather than assuming that the latest screen contains the authoritative value.
- Name the owner of order, customer and status information.
- State which outcome the user must see immediately.
- Identify any later updates the receiving system must send.
Make field definitions concrete
For each message, document required information, allowed values and the meaning of missing information. A price needs a currency and a clear interpretation; a timestamp needs an agreed time-zone convention. Use one realistic sample order to discuss these rules. Ask whether “cancelled” describes the whole order or one item, and whether an empty address means unknown or deliberately removed. Describe which records each caller is allowed to read or change. Those decisions affect both the specification and the application experience; matching field names alone does not settle them.
Specify repeated requests and useful errors
For the illustrative order, a proposed rule could be: within an agreed retention period, resending the same request identifier with identical order details returns the existing order reference. Reusing that identifier with different details produces a conflict for the caller to resolve. Define the identifier’s scope and retention period explicitly. Then distinguish mistakes that need correction from temporary failures. A timeout alone does not establish whether the order was saved, so the caller needs a way to check the outcome before deciding its next step.
- Missing delivery address: return a field-level explanation; correct the request before resending.
- Uncertain result: look up the request identifier and reconcile its recorded state.
- Temporary service failure: follow the agreed retry policy; avoid creating a fresh order identity for each attempt.
Agree how to test and change the contract
Ask both teams to walk through a successful order, a repeated request, an invalid address and an interrupted confirmation. Check that they expect the same result in each case. Keep these examples with the specification and use them when the integration changes. Name the people responsible for approving changes, notifying connected teams and investigating incidents. A handover should explain how support can trace a request without exposing unnecessary customer information, and how an incompatible change will be introduced to existing consumers.