PATCH /orders/123 shipped=1
what does this do? does it simply set a field or does it trigger a shipOrder() sequence that also sets that field? what if you need the ability to do both (eg: admin interface & customer frontend)?
I understand that in this case you can instead do something like:
POST /shipments order=123
but not everything has a record backing it that would yield to this pattern. the response to a POST is supposed to be a Location header of the created record, so in fact you do need some form of URI and record for the created shipment.
HTTP REST's multi-item and hierarchical item management are also very hacked-in and necessarily too chatty. You cannot return multiple Locations in a header, for example, when multiple records are created. Strict adherence to the purity of HTTP verbs and limits quickly degenerates into custom hackery above and beyond the RFCs for anything mildly complex.
> the response to a POST is supposed to be a Location header of the created record
The HTTP spec says otherwise:
The action performed by the POST method might not result in a
resource that can be identified by a URI. In this case, either 200
(OK) or 204 (No Content) is the appropriate response status,
depending on whether or not the response includes an entity that
describes the result.
Again the HTTP spec allows you to manage this (though not in the header):
10.2.2 201 Created
The request has been fulfilled and resulted in a new resource being
created. The newly created resource can be referenced by the URI(s)
returned in the entity of the response, with the most specific URI
for the resource given by a Location header field. The response
SHOULD include an entity containing a list of resource
characteristics and location(s) from which the user or user agent can
choose the one most appropriate.
edit: was quoting HTTP 1.0 rather than 1.1
but here is a perfect example of multiple ways to do the same thing. and the custom additions to HTTP REST begin: multiple locations in the body of the response. the fact that sometimes the headers are sufficient, but at other times, you have to just create your own API to fill in the missing functionality using the response bodies.
no me gusta.
So return the URI of a list of records. Easy.