DEV Community

Alex Georghiou
Alex Georghiou

Posted on

The REST Endpoint That Leaked a Workflow

The REST Endpoint That Leaked a Workflow

A business workflow is not necessarily a CRUD resource. Forcing every operation into PUT /thing/{id} can produce a contract nobody understands.

Consider an approval process. A client changes a field called status from pending to approved. What validated the transition? Who is allowed to approve? Can approval be reversed? Is there a notification or audit record? A generic update conceals those decisions.

An explicit transition such as POST /requests/{id}/approve can be clearer. It says the caller is requesting an action, not directly setting internal state. The server is free to reject it because the request is already approved, lacks evidence, or belongs to another approver.

This does not mean turning every field update into a verb endpoint. Ordinary resources still benefit from predictable HTTP semantics. The distinction is whether a change carries business intent that deserves its own contract.

Error responses should explain failed preconditions without exposing internal implementation. Concurrency deserves deliberate handling too: if the request changed between review and approval, do not silently overwrite another decision.

Good APIs make illegal transitions difficult to express. URL aesthetics are secondary.

Top comments (0)