Home Document Format for Non-Browser HTTP Clients

Over the past few years whenever someone proposed HTTP (and REST) as a protocol for the likes of SOA or Cloud, there has often been a discussion that because HTTP was designed with browsers in mind, it doesn't lend itself well to non-browser clients. And yet with standards like JAX-RS and associated frameworks and a range of other RESTful approaches, that concern has not dampened its adoption outside of the browser. Well with the recent announcement of the Home Documents for HTTP APIs draft proposal, the IETF is looking further at non-browser clients. In this proposal the “application/json-home” format describes resources available from a particular site as well as possible hints on how to interact with those services:

   GET / HTTP/1.1
   Host: example.org
   Accept: application/json-home

   HTTP/1.1 200 OK
   Content-Type: application/json-home
   Cache-Control: max-age=3600
   Connection: close

   {
     "resources": {
       "http://example.org/rel/widgets": {
         "href": "/widgets/"
       },
       "http://example.org/rel/widget": {
         "href-template": "/widgets/{widget_id}",
         "href-vars": {
           "widget_id": "http://example.org/param/widget"
         },
         "hints": {
           "allow": ["GET", "PUT", "DELETE", "PATCH"],
           "representations": ["application/json"],
           "accept-patch": ["application/json-patch"],
           "accept-post": ["application/xml"],
           "accept-ranges": ["bytes"]
         }
       }
     }
   }

Bill Burke, RESTeasy lead, likes the proposal but has some interest comments on it:

While I like the format, my own personal opinion is that hints are not needed.  Most(99%?) non-browser clients already know how to interact with the resources.  What they are looking for, really, is the actual URL to the resource.  IMO, a separate format(s) should be defined for resource description and the link relation URL can offer up that representation if it wants to. Another beef I have with this (and the atom link XML format too) is that the value for the relationship, rel, can be a URL.  I’d much rather define a logical name, and have a separate attribute that specifies a URL that describes the relationship.  For applications, especially intra-net based ones, URLs can change more frequently than their Internet counterparts.  A logic name attribute could remain fixed and the description URL could be more dynamic.

And as one commenter points out, perhaps one area where this proposal will really help is with human readability and understanding of the service in question? However, will humans really be reading a JSON-HOME document? Furthermore, as Mike Kelly suggests:

If you remove hints you are left with hal+json, which has been around for over a year now: http://blog.stateless.co/post/13296666138/json-linking-with-hal

Since this is only an IETF draft at the moment, now is a good time for people to provide feedback.