This looks a lot as a JSON version of what AtomPub (RFC 5023) does for XML. Collections, resource manipulation... Maybe with a bit of coordination it would be possible to extract the common elements and have them a separate RFC.
If you subtract out "HTTP can be applied to JSON", what seems to be left is a minor specification of a standardized error JSON object. There's not much "there" there; everything interesting is "left to the server".
Agreed. I was really hoping that the document would get into some best practices around the structure of the JSON objects themselves, particularly in regards to self-documenting, such as:
1. Requiring that the root of the application or domain contain metadata regarding the resources available to the JSON service.
2. Providing a common documentation and structure for nested resources, including perhaps counts and a reference URI for accessing the nested resource, along with an alternate scheme when nested resources are embedded in the resource itself.
3. Documenting how identifiers and references to other resources are included in a JSON object.
4. A standard structure for how collections should be queried (how to reference fields, specify operators, provide values, etc.)
These sorts of concerns are the things in which there's tons of variation and lots of disagreement on standardization. Using HTTP verbs to describe operations in JSON services is well understood and doesn't require much in the way of standardization.
Seems like a good idea to formalize what everyone's already doing (though requiring PATCH implementation is a good idea). Am I reading it wrong or should the 5.7 Action section say that the REQUEST URI MUST contain a query component instead of "MUST NOT"? The example contains a query component and is the only way to distinguish it from a Create operation.
Pretty interesting. I already have a homegrown version of this service running locally and powering a few side projects.
It's really useful to use that "patch" method to combine knowledge from several sources into a single representation. Seems like that problem pops up a lot on the web.
Suppose I'll add it to the list of things I thought I invented.
The "action" option is the most interesting one to me. That is not something that is a part of the general REST world. I've often thought having an rpc type interface for rest objects would be very nice but have the sense that it is very unRESTful. Is there a good balance to be had?
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.
Link to the AtomPub RFC: http://tools.ietf.org/html/rfc5023