Home Document Format for Non-Browser HTTP Clients

by Mark Little on May 27, 2012 |

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
   Accept: application/json-home

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

     "resources": {
       "": {
         "href": "/widgets/"
       "": {
         "href-template": "/widgets/{widget_id}",
         "href-vars": {
           "widget_id": ""
         "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:

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

Rate this Article


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

General Feedback
Marketing and all content copyright © 2006-2016 C4Media Inc. hosted at Contegix, the best ISP we've ever worked with.
Privacy policy

We notice you're using an ad blocker

We understand why you use ad blockers. However to keep InfoQ free we need your support. InfoQ will not provide your data to third parties without individual opt-in consent. We only work with advertisers relevant to our readers. Please consider whitelisting us.