Name the business contract, not the transport trick
Start with the domain action or query the client needs. HTTP paths, queue topics or provider APIs are implementation details around that contract.
- Define required inputs and validation.
- Define success and non-success states.
- Identify source-of-truth ownership.
Errors should be actionable and stable
Distinguish validation, authorization, conflict, provider uncertainty and internal failure. Avoid leaking raw provider errors directly into every client.
Retries must not create duplicate business actions
Any operation that can be retried by a browser, worker, provider or network layer should have a documented duplicate-handling strategy.
Change contracts deliberately
Prefer additive changes when possible. For breaking changes, version the contract or provide an explicit migration window rather than silently changing meaning.
Public documentation boundary
This guide documents patterns. It does not claim that a specific Thonem API path exists unless that path is documented by the implementation itself.