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
   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"]

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.