

Internet-Draft: A Convention for HTTP Access to JSON Resources - jkbr
http://tools.ietf.org/html/draft-pbryan-http-json-resource-01

======
gioele
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.

Link to the AtomPub RFC: <http://tools.ietf.org/html/rfc5023>

------
jerf
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".

~~~
ryanbrunner
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.

------
benblair
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.

~~~
georgecalm
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?

------
djtriptych
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.

------
macrael
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?

------
georgecalm
Can someone elaborate on the "5.7 Action" please? What's the use-case?

~~~
jkbr
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.

~~~
ryanbrunner
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.

~~~
yesbabyyes
_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.

~~~
jkbr
You are right. The aggregation wasn't a good example of an "action".

