26th
Grape in the Path of The Steamroller of ProgREST
Recently Joe Gregorio posted about RESTful JSON. It generated such lively comments that a mailing list/google group was created. Discussion has been flying along at a brisk pace, a fair number of people trying to locate the common ground.
This is great, clearly there is a need for something, otherwise the audience wouldn’t gather so quickly; but, you know, I can’t figure out what the hell these guys are talking about. I’ve been through this sort of thing enough of the time to know that the problem is that the context I’m bringing to the conversation is different from the context others are bringing.
Joe says
What we seem to need is a data-oriented REST protocol. We already have document-oriented REST protocols covered with the Atom Publishing Protocol, but what if the information you want to convey is data, i.e. doesn’t have the minimum meta-data to qualify as a document, such as an author, title, published data, and id. If you’re going to be slinging data around these days the best thing is probably JSON, so what would RESTful JSON look like?
and then proceeds to stub out some ideas on how to represent collections of stuff in a JSON representation that allows efficient access and management over HTTP. On the mailing list these ideas have been extended to include issues surrounding partial updates of resources. There appears to be confusion about what the resource is. Is a resource a thing and its attributes? Are the attributes yet more resources? Is a collection a resource itself? There appears to be confusion about the distinction between a representation of a resource (the JSON itself) and the resource (the stuff that the representation represents). This confusion seem to be leading to a desire to create a universally applicable URL structure that will assist access to “objects” that exist somewhere (e.g. some people want to model things to be helpfully aligned with ActiveRecord, Jester, and associates).
This doesn’t sound like REST to me. At least not the REST that I imagine in my head. I’m comfortable with imagining my own version with REST because as far as I can tell that’s what everybody does: They take the parts they like and create a world view which makes them comfy, and they argue about it for fun, or at least a diversion.
In a comment on Joe’s posting I said:
At core here I guess my confusion is that I don’t understand the phrase “RESTful JSON specification”. JSON is a content-type, something we might like to see some of our resources represented as as we transfer them about. Can you be more explicit about why the specification should exist? You’ve said to me that most RESTful APIs you’ve seen end up being RPC, but that doesn’t strike me as an answer to the question so much as an observation about a sad (but true) state of affairs.
in his response Joe said:
“Just use HTTP” doesn’t seemed to have worked out so far as the vast majority of JSON based APIs are RPC.
We seem to have missed one another entirely there.
Especially as on the mailing list people seem intent on formalizing a way to do gets and sets on “objects” on the server. Feels like RPC to me.
One of the REST essences that I hadn’t made concrete in my own brain until Dare decided to explain REST to Damien Katz is the idea that by introducing some complexity in the client, services can more effectively scale and be more robust in the face of weirdness. I was already establishing that expectation in services I was making (i.e. this here service, it’s got some resources, if you want to do some things with those resources, well then, how about you GET them, do some stuff with them, and then PUT them back, thank you very much) but hadn’t realized I was doing something sanctioned. I had realized that the choice made things easy to build, test, use, deploy, improve, explore, etc.
What I’m seeing on the restful-json mailing list is people wanting to lessen bytes on the wire and explicitness of client requests at the cost of increased complexity in both the server and the so-called protocol (AtomPub, for example) involved. They hope to alleviate the cost of managing moving the complexity around (or even expanding complexity on all dimensions) by creating a layer of abstraction (a protocol) to contain the complexity.
This leads me to conclude that perhaps the people who are interested in RESTful-JSON are primarily concerned with internally deployed systems where they can be in charge of both ends of a request and handle requirements for supporting the protocol. Managing such a dependency in closed systems is easy to do and warranted where there are special requirements.
However, on the wide open web I can’t see it playing. It may be counterintuitive to many developers, but making additional protocol requirements is a turn off for exploration, learning, experimentation and innovation. Protocol abstractions are certainly useful, but they also have their costs. ws-* is too much like hard work and I’m beginning to feel the same way about AtomPub, let’s keep JSON fun. We want a heterogenous web, a diverse web, a web of learning and exploration with resources at cool URIs doing and/or being cool stuff.
For my own purposes, out on the open web, JSON is a content-type, a possible serialization for some resources that I want to put on the web. The protocol is HTTP.
