BT

New Early adopter or innovator? InfoQ has been working on some new features for you. Learn more

Home Document Format for Non-Browser HTTP Clients

| by Mark Little Follow 2 Followers on May 27, 2012. Estimated reading time: 2 minutes |

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.

Rate this Article

Adoption Stage
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Discuss

Login to InfoQ to interact with what matters most to you.


Recover your password...

Follow

Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.

Like

More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.

Notifications

Stay up-to-date

Set up your notifications and don't miss out on content that matters to you

BT