Your domain has operations that are not create/read/update/delete — cancel an order, resend an invitation, retry a failed payment. How do you fit them into an HTTP API contract, and which method do you choose?

## The mismatch REST's uniform interface gives you a small set of methods over resources. Most business systems also have *operations* — cancel, refund, publish, archive, resend, retry, approve, merge. They are not naturally "set a field", and forcing them into pure CRUD produces contracts nobody can read. The good news is that POST is not "create". POST is defined as: process this representation according to the resource's own semantics. Creation is the most common case, not the definition. So a POST that performs an action is entirely within the protocol — the design question is only what URL it targets. ## Shape 1: action sub-resource ``` POST /orders/42/cancel Content-Type: application/json {"reason":"customer_request"} HTTP/1.1 200 OK {"id":42,"status":"cancelled","cancelledAt":"2026-08-12T10:00:00Z"} ``` Why it works: the intent is explicit in the URL, so logs, metrics, rate limits and authorization policies can all target the specific operation (`orders:cancel` scope). It reads well in documentation and in client code. Why purists object: a verb appears in the path. In practice this is the dominant pattern across mature public APIs, and the readability gain outweighs the theory. Keep it disciplined — a small, named set of actions, not a general RPC-over-HTTP layer where every endpoint is a verb. ## Shape 2: the action as a resource ``` POST /orders/42/cancellations {"reason":"customer_request"} HTTP/1.1 201 Created Location: /orders/42/cancellations/9 ``` This is the stronger design when the action is itself an entity: it has attributes, an actor, a timestamp, maybe an approval workflow; you want to list past attempts (`GET /payments/42/retries`); or the operation is asynchronous and needs something to poll. Refunds are the canonical example — a refund is a real business object, not a state flag. It also solves multiplicity naturally: three resend attempts are three `invitations/{id}/deliveries` records, whereas `POST .../resend` gives you nothing to inspect. ## Shape 3: state field via PATCH `PATCH /orders/42` with `{"status":"cancelled"}` keeps the interface purely resource-oriented. It is a reasonable fit when the transition really is just a field change with modest consequences, and when clients benefit from a single update endpoint. It goes wrong when the transition has heavy side effects. The request body says "set a string"; the reality is refund, email, inventory, ledger entry. Authorization gets awkward too — you now need field-level rules inside a generic update endpoint, instead of a distinct permission on a distinct endpoint. And multiple legal transitions with different preconditions turn into a switch statement inside the patch handler. ## Cross-cutting rules for action endpoints **Method.** POST. Not GET — actions triggered by prefetchers, crawlers and caches is exactly the failure mode covered by GET's safety requirement. PUT only if you can honestly express it as "make this sub-resource have this state" (`PUT /orders/42/status` is a defensible middle ground, idempotent by construction). **Response.** Return the affected resource's new representation with `200`, or `201` + `Location` if you created a record. That saves the client a refetch and makes the outcome unambiguous. **Illegal transitions.** Cancelling a shipped order is a conflict with current state → `409` with a stable code and the current status in the body, so the UI can say something useful. Not `400`, which suggests the request itself was malformed. **Idempotency.** POST is not idempotent, so a timed-out retry may cancel twice, refund twice, or send two emails. For money or messages, accept an `Idempotency-Key` and return the original response for a repeat. Alternatively design the action to be naturally idempotent ("cancel an already-cancelled order" returns 200 with the same state rather than erroring) — but be careful that this does not mask duplicate refunds. **Async actions.** If the work is long (a bulk archive, a large refund reconciliation), return `202` with a job/status resource rather than holding the connection. **Authorization.** One of the strongest arguments for distinct action endpoints: `orders:cancel` is a separate permission from `orders:update`, and separate endpoints make that trivially expressible and auditable. ## Choosing quickly Does the action produce a record anyone will want to inspect or list? → resource (shape 2). Is it a genuine one-off command with side effects? → action sub-resource (shape 1). Is it truly just a field change? → PATCH (shape 3). All three are respectable; inconsistency between them within one API is not.