Design APIs around workflows, not resources
Shape endpoints around the job being done so clients orchestrate less and systems stay easier to change.
Quick Take
Resource-first APIs often push orchestration complexity onto clients and create chatty, fragile integrations. Workflow-first APIs expose intent directly, reducing round trips and making correctness easier to enforce server-side. The result is simpler clients and more stable evolution when internals change.
Resource APIs leak orchestration into the client
When an API is organized only around nouns, clients often need multiple calls to complete a single user action: fetch state, check eligibility, create something, update something else, then poll for completion. This makes clients responsible for sequencing, retries, and partial failure handling.
That orchestration does not disappear. It becomes duplicated logic across web, mobile, and partner integrations. The API stays "clean," but the system becomes harder to reason about.
Workflow APIs encode intent and reduce round trips
A workflow endpoint represents a job the user is trying to complete, not the storage shape underneath it. Examples are "place order," "reserve inventory," "submit claim," or "generate invoice." The server owns sequencing, validation, and transactional integrity across internal components.
This makes performance and correctness easier to manage. Fewer calls reduces latency and failure surface. Centralizing rules reduces divergence between clients.
Keep resources as primitives, workflows as the interface
Workflow-first does not mean abandoning resources. Resources are useful as stable primitives for read models, admin tooling, and narrow updates. The mistake is treating resources as the only interface shape.
A practical approach is to expose workflow endpoints for primary user actions, while keeping resource endpoints for retrieval and controlled edits. Version workflow contracts explicitly, because changes to "intent" semantics break clients faster than changes to internal data layout.
Signal
Most teams underestimate how quickly "clean REST" turns into client-side business logic. If the client needs a playbook to complete a single action, the API boundary is in the wrong place.