APIs are contracts between parts of the business.
An API that responds successfully is not necessarily an integration that preserves business correctness. System boundaries need ownership, failure semantics, observability and a predictable way to evolve.
If the response is lost, who knows whether the order exists?
Define state ownership, idempotency and reconciliation as part of the business contract. An HTTP success code alone cannot make two applications agree.
Follow one transaction across the boundary.
An illustrative order request demonstrates the uncomfortable interval between sending a write and knowing its result. The API owner must make that interval recoverable.
The contract
contract_version- An explicit supported schema and a compatibility policy for consumers.
operation_key- A stable business operation identifier, scoped and retained by a documented rule.
request_fingerprint- A way to reject reuse of the same key with a materially different payload.
state_owner- One authoritative service owns acceptance, cancellation and current order state.
status_reference- A durable lookup path for resolving a timeout or delayed acknowledgment.
Send
- Caller / consumer
- Submit the order with its stable operation key.
- State owner
- Validate authority and schema, then record the operation and business state consistently.
Timeout
- Caller / consumer
- Treat the outcome as unknown; keep the same key.
- State owner
- The order may already be accepted even though the response was lost.
Resolve / retry
- Caller / consumer
- Query status or repeat the same operation under the contract's retry policy.
- State owner
- Return the recorded result or process once. Reject a conflicting payload under the same key.
Repeated event
- Caller / consumer
- A consumer receives a delivery it has already seen.
- State owner
- Deduplicate against the business effect; delivery count is not transaction count.
Reconcile
- Caller / consumer
- Compare the local view with authoritative order state.
- State owner
- Expose enough state and diagnostic identity to repair disagreement.
Inspect the evolution rules
- A new optional field
- Verify tolerant consumers rather than assuming compatibility.
- A changed field meaning
- Treat semantic changes as contract changes, even if the JSON shape is identical.
- A delayed or reordered event
- Use explicit state/version rules; arrival order is not business order.
Illustrative API contract and event trace. These are design fields, not a live endpoint or service claim.
Inspect the failure semantics.
- A versioned contract naming state ownership, timeout, retry and key-retention rules.
- A repeated-request and out-of-order-event test trace.
- A reconciliation procedure with correlation identifiers and an exercised partial-outage path.
Queues solve a particular coordination problem.
A small synchronous workflow may need a direct API. Introduce events and queues where asynchronous state and failure recovery warrant them, with an owner for replay and reconciliation.
The platform engineering argument
For CTO, CIO, CPO, COO
The situation behind the request
Two applications disagree on whether an order was accepted, updated or canceled. A retry writes a duplicate transaction because the message broker delivered the event again.
Where the obvious solution falls short
Without idempotency, state ownership and reconciliation, every connected service amplifies errors. An AI feature acting through these APIs adds new uncertainty unless tools are carefully scoped.
How we would approach the work
Define domain events, ownership, schemas and recovery. Prefer stable platform capabilities and build bespoke interfaces only when integration requirements warrant them.
What the engagement may include
- Service/API contracts and versioning policy.
- Event, queue and integration design with idempotency.
- Observability, dependency tracking, retry and reconciliation.
- Documentation, automated integration tests and release planning.
The choices worth making explicitly
Direct API calls may be right for a small synchronous workflow. Events and queues may be required for asynchronous stateful work. Complexity should follow actual reliability needs.
What we would test before calling it ready
Exercise schema version changes, out-of-order events, credentials rotation, repeated requests, partial outages and replay.
A sensible first step
Start with a transaction whose success can be verified across system boundaries.