Software design and procurement
Writing API integration requirements for a software brief
Specify identifiers, retries and reconciliation for a connection between a council work-order system and a contractor’s scheduling software.

A council sends a repair to a contractor. The contractor’s scheduling system creates the job, but the acknowledgement never reaches the council. If someone presses send again, will two crews turn up? This is a practical starting point for commissioning an API integration between organisations.
Name the record that each system owns
Give the council work order and the contractor job separate identifiers. Record the relationship between them. Decide which system owns the location, the appointment, the completion note and the public status. Those choices determine what happens when a field changes while a crew is already travelling.
Use an invented example in the specification. Work order WO-18 concerns a damaged gate at the east entrance. The contractor assigns job C-91 and books Wednesday morning. If staff change the entrance to the west gate, the booking should retain its identity and the crew should see the revised location. Agree who can cancel that job.
Describe a missing acknowledgement in plain English
Ask the supplier to show how the same request can be recognised on retry. The council should be able to recover the contractor’s reference after a communications interruption. Write down when retries stop, who sees the exception and which data the operator needs to resolve it. Keep sensitive job notes out of ordinary alerts.
The receiving supplier may only make its API available during defined hours or may change it on a different release schedule. Ask both parties who provides a test environment, how changes are announced and how the buyer learns that the queue has stopped moving. Include those costs in each quote.
Reconcile a day’s work
Prepare a small test set covering a new job, a duplicate send, a cancellation and a completion received after the work order was closed. Reconcile counts and individual references across both systems. A green status indicator is weak evidence if one system lists two jobs for the same repair.
At handover, give the service desk one unmatched item. Check that a staff member can find its last successful step, identify the responsible team and record how it was resolved. Specify this as an observable requirement in the brief. New Zealand Government Procurement’s requirements guidance is a starting point for documenting what the buyer needs delivered.