Internet-Draft: A Convention for HTTP Access to JSON Resources(tools.ietf.org)
tools.ietf.org
Internet-Draft: A Convention for HTTP Access to JSON Resources
http://tools.ietf.org/html/draft-pbryan-http-json-resource-01
13 comments
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.
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.
Yeah, I think it's a typo too (especially with the ?{query} there in the spec. Btw, do you understand the purpose of this Action?
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.
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?
Can someone elaborate on the "5.7 Action" please? What's the use-case?
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}
POST /orders?action=process-queue HTTP/1.1
HTTP/1.1 204 No Content
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.
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.
They have done that. See 5.6. Query. Just a mistake by the parent.
You are right. The aggregation wasn't a good example of an "action".
[deleted]
Link to the AtomPub RFC: http://tools.ietf.org/html/rfc5023