First, check if the action is really a state change. Cancelling an order can be PATCH /orders/981 with {"status":"cancelled"}. The server checks which status changes are allowed. If the order has already shipped, it returns 409 (Conflict).
If the action has its own data or its own lifecycle, model it as a resource. For example:
POST /orders/981/cancellationswith a reason creates a cancellation record. Clients can read this record later.- Resending an invoice email can be
POST /invoices/55/deliveries. It returns 202 (Accepted), because the email is queued and sent later.
If neither fits, use a controller-style action like POST /orders/981/cancel. This is a practical compromise, and many APIs use it. Use POST for it, because it changes state. Keep these actions few and documented. Do not let them replace normal resource design with RPC style (calling functions by name over HTTP).
- A state change can be a PATCH on a status field.
- Actions with their own data become sub-resources created with POST.
- Return 409 for a status change that is not allowed, and 202 for queued work.
POST /resource/{id}/actionis an acceptable fallback.
Read more
- HTTP request methods (MDN) (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)developer.mozilla.org
- 409 Conflict (MDN) (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409)developer.mozilla.org