json-home format: resource discovery

May 11, 2012

Thank you Mark Little for turning me on to the JSON-Home format Internet Draft. “application/json-home” is a format that 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"]
         }
       }
     }
   }

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.

BTW, I’m glad that the powers-that-be at IETF are showing some love to non-browser clients. Json-home is something similar I’ve done for a few of the RESTful services I’ve written.

Joe Littlejohn (@joelittlejohn)
May 11, 2012 @ 20:37:38

Nice. Any chance we could see support for generating this document automatically in RESTEasy sometime soon?? 🙂

One of the great benefits of this document is that it’s human-readable. Human’s will find the list of hints very useful, particularly if they’re new to your service.

Regarding link relations, unless I’m missing something, you are free to use your logical names (these are valid link relations). As you say, the rel _can_ be a URL, not _must_. Is your beef that you would prefer to see using URLs as values *explicitly* disallowed?

billburke
May 12, 2012 @ 14:39:00

AFAIK, the “rel” attribute of a link must be a URL unless it is registered with IANA.

Yes, I have plans to implement JSON-HOME support and maybe Swagger integration.

- Ryan J. McDonough
  Aug 10, 2013 @ 18:01:21
  
  RFC5988 doesn’t state that the value must be URL, but rather that the “rel” value must be a URI. With that said, it’d be acceptable to use a URN instead of an HTTP URL.
billburke
May 12, 2012 @ 14:42:08

On one more thing, human readability is fine, but IMO, humans will not normally be reading a JSON-HOME document, this is why, IMO, all metadata information should be linked to instead of sent. It reduces marshall/unmarshal time on the client and server and allows a bit more freedom for resources to fool around with different service description formats (WADL, Swagger, etc.).