It defines a generic mechanism for performing actions that don't fit the GET/PUT/PATCH/POST/DELETE model on resources and collections. For example aggregations:
POST /orders?action=sum&field=price HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{"sum": 9000}
Or actions with side effects:
POST /orders?action=process-queue HTTP/1.1
HTTP/1.1 204 No Content
Which is better than creating a specific resource for each of the "actions", such as /orders_sum_price or /orders_process_queue, because it keeps the URIs clean.
I like the idea of having a standardized way of dealing with actions (I run into this quite often when dealing with resources that are state machines), but I'm flabbergasted as to why something like a 'sum' action must be sent with a POST verb.
POST is supposed to be "used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.", which is nonsensical for querying information like sums from collections, and furthermore is supposed to be non-idempotent, which isn't true for a sum operation.
Ideally "action" would be seperated into two different methods, one for manipulating resources (like state machine transitions, or other processing), and one (utilizing GET) for aggregations and computations on collections or resources.
Ideally "action" would be seperated into two different methods, one for manipulating resources (like state machine transitions, or other processing), and one (utilizing GET) for aggregations and computations on collections or resources.
They have done that. See 5.6. Query. Just a mistake by the parent.
