Request and response contract
For each connection, agree which system owns the data, who may start the request, and which operations are available. A lookup contract should identify the input fields, how they are validated and which fields may be returned. For a write, specify the record to change, which changes are permitted and how the caller can identify the resulting operation.
Agree how the integration authenticates to the other system, which permissions its credential needs and where the credential is stored and rotated. If the request involves customer data, define how the user’s identity is verified and how the application checks ownership. Record the intended response for invalid input, missing permission, unavailable services and an outcome the caller cannot yet confirm.
Worked example from Reesponder
In the Reesponder product walkthrough, a customer asks to add a game to their basket. The customer reviews the product and quantity before confirming. The demo shows the completed basket action returning the total and a link to checkout. That sequence defines three separate states for the interface to show: the proposed change, the request in progress and the result returned by the store.
In the implementation described in the engineering case, editing an action changes its configuration revision, disables the action and cancels pending proposals for the earlier version. When a customer confirms a proposal, the application checks the revision and eligibility again as it claims the request. That gives the confirmation a precise meaning even if the configuration changes while the customer has the review screen open.
View the product walkthrough or read the case study on confirmed actions.
Delivery state and retry rules
A request that changes an external system can reach that system and succeed before the response is lost. Agree how the application records an uncertain outcome and how it can check what happened. A status lookup or a stable operation identifier can help when the external service supports one. If a provider accepts an idempotency key, verify which operations it covers and how long the provider remembers it before deciding when a retry is safe.
Also decide how the local application handles repeated confirmations and worker restarts. Reesponder uses a database transition to give one execution attempt ownership of a pending action. Local execution ownership and the external provider’s retry contract cover different parts of the workflow. The application records an uncertain write when the result cannot be established. Read the Reesponder case study on lost responses.
Acceptance checks for a connection
- Submit a valid lookup and compare the returned fields with the agreed mapping. Repeat with an invalid input and confirm that the request ends before a provider call is made.
- Try to access a record outside the verified customer’s account. Confirm the request is rejected and the response avoids exposing private information.
- Submit the same confirmation twice and check that the application gives one attempt ownership of the write. Change the configuration before confirming an older proposal and check that the stale proposal is blocked.
- Exercise a lost response after a provider accepts a write. Verify that the recorded outcome remains uncertain until reconciled and that the application follows the agreed retry rules.