REST APIs: agree the contract before connecting systems

A product price changes in one system but remains unchanged on the website. A connection exists, yet nobody has agreed which system owns the price or who investigates a failed update. An endpoint list cannot supply that agreement.

Start with the business outcome: publishing products, updating availability, transferring orders or returning a status. Describe each direction separately. “The systems will synchronise” is too broad to define a workable integration.

Define ownership and stable identifiers

Agree identifiers for products, variants and orders. Names make weak keys because they can change or be duplicated. Specify currencies, date formats and the meaning of an empty value.

Record which side creates and updates each field. When both can edit the same information, define conflict resolution. Distinguish deletion, temporary hiding and zero stock.

Describe actions and responses

Roy Fielding’s 2000 dissertation introduces REST as an architectural style. Returning JSON alone does not establish compliance with every REST constraint. The practical agreement still needs clear resources, permitted actions and response meanings.

Prepare examples for invalid data, insufficient permission and an unavailable service alongside successful requests. Keep secret keys out of the browser and public source. Grant each side only the necessary permissions and define how access can be changed.

Expect interrupted communication

A connection can fail after the receiving system has stored a record. A retry should not create another order. Define safe repetition, visible failures and later reconciliation. Retrying forever is not a recovery plan.

1. Use realistic but non-confidential test records.
2. Check creation, updates and repeated requests.
3. Test denied access and a temporary outage.
4. Compare the final records in both systems.
5. Assign responsibility for receiving alerts and resolving failures.

A useful web integration provides an agreed, testable connection. Plan how it will be maintained when either system changes, rather than treating the first successful request as completion.