Designing APIs for stateful flows: Don't make clients guess or obey

In many stateful systems, API failures aren’t caused by missing endpoints, incorrect schemas, or misinterpretations. They come up because the system doesn’t clearly define who’s responsible for coordination. These problems often appear in multi-step flows, where progress unfolds over time and across devices. Users may leave and return later. Steps may complete out of order. Some actions may be temporarily disallowed. Retrying is normal, and more than one client may exist. In such systems, coordination is unavoidable. The only question is whether it’s handled explicitly, or whether it leaks into places where it doesn’t belong. Example: A multi-step flow Consider a user onboarding flow that involves identity verification, accepting terms, and configuring payment. Some steps may already be complete, others blocked. Users may resume the process days later on a different device. At any moment, the system has a true state: what has been completed, what’s required, what’s allowed, and what’s…