CodePark/ questions / REST resource design
START PRACTICINGPRACTICE
Backend question · HTTP & API design › REST resource design

How would you model actions that are not plain CRUD, such as cancelling an order or resending an invoice email?

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/cancellations with 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}/action is an acceptable fallback.