API Design

Make consumer-visible semantics explicit enough that providers and consumers do not have to guess.

Workflow

Identify the consumer job, domain terms, authority, sensitivity, and failure modes.
Choose the interface shape that fits the interaction: request/response, query, command, event, webhook, or stream.
Define representation semantics: identifiers, absent vs null, defaults, enums, timestamps/units, ordering, filtering, and pagination.
For mutations, define validation, preconditions, idempotency scope, concurrency behavior, partial outcomes, long-running operations, and retry-safe errors.
For async contracts, define delivery/duplicate/order semantics and how consumers detect gaps or replay.
Evaluate compatibility from each consumer perspective and plan additive evolution/deprecation where possible.
Keep implementation framework and storage details out of the public contract unless they are intentionally part of it.

Stop when a consumer can implement correctly without guessing success, failure, retry, compatibility, or data semantics.