A state field records a resource’s current position in a defined lifecycle, such as an email being draft, sent, or unsent. It represents state rather than ordinary scalar data. section 9.1.1 section 25.3.1
Treating a state transition as an ordinary update can confuse clients, because changing state may trigger actions beyond storing a new value. Sending an email, for example, also requires delivering it to recipients. Dedicated custom methods keep data updates separate from lifecycle transitions and their side effects. section 9.1.1
Choose the representation according to the lifecycle:
- Use a state field when the resource has several states connected by a well-defined lifecycle or state machine. section 25.3.1
- For soft deletion alone, prefer a Boolean deleted field; reuse an existing state field only when adding a deleted state fits the established lifecycle. section 25.3.1
- Expose transitions through purpose-specific methods when changing state performs additional work or should be controlled by the service. section 9.1.1 section 25.3.1
Sending an email
An email may expose state: 'draft' or 'sent', but UpdateEmail({state: 'sent'}) is misleading because it appears to store a field while also initiating delivery. A purpose-specific send operation communicates the transition and its side effects more clearly. section 9.1.1
