In this chapter
9.1 Distinguish a command from a fact
A command asks an authority to decide or perform an action. An event describes a fact that has already occurred under a named authority. An API can carry either interaction; a broker does not turn an invalid fact into a valid one. In the worked example, ApproveRequest is a command directed to the request boundary. RequestApproved is a fact emitted only after a valid transition commits. A notification service may consume the fact but cannot change what was approved.
9.2 Contract fields and semantics
| Contract element | Required definition | Failure if omitted |
|---|---|---|
| Actor and organizational scope | Derived and checked by the authoritative service | A valid account acts in the wrong department |
| Request ID and expected version | Identify the object actually reviewed | Approval silently targets changed content |
| Command identity | Scope, payload comparison and retention | Retry creates another business operation |
| Event identity and schema version | Stable event ID and compatible meaning | Consumers misinterpret or duplicate work |
| Failure response | Rejection, conflict, retryable failure or unknown outcome | Client retries blindly |
9.3 Commit and delivery sequence
Record the state change and outbox intention within one transaction. A worker claims committed work, delivers it and records progress. If delivery succeeds but acknowledgement is lost, processing may repeat. Consumers therefore require deduplication or idempotent effects; the outbox is not an end-to-end exactly-once guarantee. Ordering should be specified per business object when later facts depend on earlier ones. A global ordering requirement can impose unnecessary coordination. Decide how a consumer detects a missing predecessor, retries processing and exposes work that cannot proceed.
9.4 Compatibility and partner onboarding
Changing a field name is not the only breaking change. Reinterpreting “approved amount,” changing currency meaning or omitting an event for a previously included state can break a consumer without changing the schema shape. Maintain contract owner, version, example payloads, error catalogue and deprecation policy. Before a new integration is enabled, verify identity, permitted data, rate behaviour, timeout handling, replay behaviour and a named support route. Do not treat possession of an API key as agreement on business responsibility.
9.5 Verification matrix
- Repeat the same command after an ambiguous timeout.
- Change the payload while reusing its key and verify a defined refusal.
- Deliver an event twice and verify one intended business effect.
- Process a compatible old payload and reject an unsupported version clearly.
- Interrupt the worker and recover pending work without losing its trace.
The output is a contract catalogue and testable interaction design. A broker or gateway purchase follows only when its capability is required and operated.