CRUD, REST, and the Case for Explicit Commands

CRUD and REST are built around resources and their fields. You update a document by sending a PATCH request with field changes. You delete a record by sending a DELETE request. But what if you want to "submit" a document? Or "approve" a request? Or "escalate" a case?

These actions don't map cleanly to CRUD operations. Teams often resort to:

• PATCH updates with special fields: PATCH /documents/123 {"status": "submitted"}. This looks like a field update but is actually a state transition with rules and side effects.
• Verb-like endpoints: POST /documents/123/submit. This works but feels like a workaround, and REST purists might object.
• Action fields in update payloads: PATCH /documents/123 {"action": "submit"}. This mixes data updates with action execution.

None of these approaches feel natural because they're trying to force actions into a resource-centric model.

When actions are forced into PATCH updates or special fields, the frontend often becomes responsible for:

• Determining valid transitions: The UI must know which status values are allowed in the current state
• Enforcing permissions: The frontend decides which actions to show or hide based on user roles
• Validating preconditions: The UI checks if required fields are filled before allowing an action
• Handling workflow rules: The frontend orchestrates multi-step workflows

This creates several problems:

• Duplication: Business logic exists in both frontend and backend, and they can drift out of sync
• Security gaps: Frontend validation can be bypassed; the backend must still validate everything
• Complexity: The frontend becomes a workflow engine rather than a presentation layer
• Maintenance burden: Changes to business rules require updates in multiple places

When the backend only accepts field updates, it behaves like a passive repository. It stores whatever the frontend sends, validates field formats, but doesn't govern behavior. The backend doesn't know that "submitting" a document is different from "updating" its status field.

This creates a fundamental mismatch: collaborative systems need the backend to be an active governor of behavior, enforcing transitions, validating permissions, and managing side effects. But CRUD/REST encourages a passive model where the backend just stores data.

The result is that critical business logic—what actions are allowed, who can perform them, what preconditions must be met—ends up scattered across frontend code, API middleware, and database constraints, making it hard to reason about and maintain.

Explicit command interfaces treat actions as first-class citizens. Instead of updating fields, you send commands:

Each command has:

• Explicit name: The command name clearly expresses the business action
• Parameters: The data needed to execute the command (document ID, reason, etc.)
• Rules: Validation, permissions, and preconditions are part of the command definition
• Side effects: Commands can trigger events, notifications, and other system changes

When the backend exposes explicit commands, the frontend becomes simpler:

• Query available commands: The UI can ask the server "what commands are available for this document?" and display buttons accordingly
• Send commands directly: When the user clicks "Submit," the UI sends the submit command—no need to figure out which fields to update
• Handle results: The command returns success or a clear error message, making error handling straightforward
• No workflow logic: The UI doesn't need to know state machines, transitions, or business rules

The UI becomes a presentation layer that queries available commands and sends them when users act. All the complexity stays on the server where it belongs.

Command interfaces make APIs self-documenting. When you see POST /commands/submit-document, you immediately understand what it does. Compare that to PATCH /documents/123 {"status": "submitted"}, which requires reading documentation to understand the implications.

Commands also make it easier to:

• Audit actions: Command logs clearly show what actions were taken, not just what fields changed
• Debug issues: When something goes wrong, you can see exactly which command was sent and why it failed
• Test behavior: You can test commands in isolation, verifying that they enforce rules and produce correct side effects
• Version APIs: Commands can be versioned independently, allowing gradual migration

In the State-Based Collaboration Framework, actions are explicit commands. Each action has:

• A name: Clearly expresses the business intent (SubmitDocument, ApproveRequest, EscalateCase)
• Parameters: The data needed to execute the action
• State reducer: A pure function that validates the action, checks permissions, evaluates guards, and computes the new state
• Event emission: Actions generate events that are recorded and can trigger side effects

The framework ensures that actions are evaluated in the context of the current state, with all rules and permissions checked before any state change occurs. This makes the system deterministic, testable, and auditable.

By using explicit actions, the framework avoids the CRUD/REST problems:

• No field updates masquerading as actions: You don't update a status field; you execute a Submit action
• No logic in the frontend: The frontend queries available actions and sends them; all business logic is on the server
• No passive repository: The backend actively governs behavior, enforcing state machines, validating permissions, and managing transitions
• Clear intent: Every API call expresses a business action, making the system easier to understand and maintain