I was asked to help out with work on a bunch of Cloudy APIs and naturally I’m trying to make them RESTful. It dawns on me that, very often, client-to-server messages can be expressed as name-value pairs, and that doing this is on balance A Good Thing.
In particular I was seeing, in HTTP exchanges, a lot of client-to-server messages (POSTs and PUTs) that looked something like this:
<node> <time-to-live>300</time-to-live> <threshold>88.5</threshold> </node>
I saw almost no instances of nested structures, long-running text or the
other things that scream “XML!” My first thought was “JSON, maybe?” but, you
know, that’s maybe overkill too, why not just do name-value pairs like an HTML
application/x-www-form-urlencoded (Near as I can tell,
the normative reference is
the HTML spec; gack.)
Note that in the above example, the resource I’m sending this to represents a Node, so one layer of XML markup is superfluous.
Pro · Why would you do this, rather than than use XML or JSON? Well, because then you can get at your API through a Web browser. All you have to do is program the server to send HTML to browsers and XML (or JSON) to non-browser clients, which is pretty easy with modern frameworks like Rails. Maybe I’m missing something, but this seems like a huge advantage.
Con · I can see two problems. First, you are quite likely to feel internationalization pain; XML may not be perfect but it does make sure that client code builders have to think through the i18n. There are almost certainly going to be certain combinations of browser releases and form designs that will screw up some character encodings.
Second, browsers really only do GET and POST, and the U and D parts of CRUD map nicely in the natural REST idiom to PUT and DELETE, which are usefully idempotent. In fact, I still have bruises from batterings administered by Joe Gregorio, during the design of AtomPub, to anyone who felt that maybe the use of PUT and DELETE was not totally essential.
So, granted. But maybe Joe needs a bigger club, because I have to admit that limiting myself to GET and POST just doesn’t cause me that much heartburn.
Everybody Else Knows This Already · At least I suspect so. The years I spent grinding away on AtomPub, which is all about CRUD on documents and blobs, left me with blinkers.
Anyhow, on balance, I’m increasingly inclined to believe that there is a large class of simple administrative-CRUD apps where you can send those name-value pairs upstream, and the advantages may make it worthwhile living with both fighting the i18n fires and a certain loss of RESTafarian purity.