[json-home] post draft-02

[nickl-]

Well done!

I was totally caught by surprise to see the document number ++, you made my day. =)

You can consider me an early adopter so I did some research trying to imagine where this might end up and this is the resulting document for your perusal.

The following considerations were made and guidelines followed:

1. I only reused items from existing specifications which I consider to be suitable additions. ymmv
2. The relevant references have been added sparingly with my illegal comments. Should you require more detail, I can oblige.
3. I chose to use URNs (RFC2141) instead to differentiate, between type identifiers and links.
4. I've added a header "property" as per RFC6415, with general links which relate to all resources.

The result is speculative only in hope to be utilized as a basis for further discussion which I'll continue on list @apps-discuss unless you have another preference.

{
  "expires":"2012-06-07T09:30:00Z", 
  "urn:fooapi:property": {             // urn RFC2141 RFC6415 
    "titles":{
      "default":"FOO Api",
      "en-us":"FOO Api"
    },
    "type": "http://protocol.example.net/version",                     
    "copyright": "http://example.com/copyright",                       
    "version": "0.1.0",                                                
    "license":{                                   //RFC 4946 
      "type": "application/rdf+xml",
      "href": "http://creativecommons.org/licenses/by-nc/2.5/rdf"
    },
    "disclosure": {                               //RFC 6579
      "href": "http://example.org/ipr/meta-spec",
      "title": "Patent Disclosures List"
    },
    "hub": {"href": "http://example.com/hub"},                         
    "monitor": {                                  //RFC 5989
      "href": "http://www.example.com/pet-profiles/alpacas/",          
      "hinst":{
        "allow": ["GET", "SUBSCRIBE", "PUBLISH"]
    },
    "lrdd": {"href-template": "http://example.com/lrdd{?uri}"},     
    "author": {"href-template": "http://example.com/author{?uri}"}, 
    "edit": {
      "href": "http://example.com/edit{?uri}",
      "hints": { "allow": ["GET"], "representations": ["text/html"]}
     }
  },
  "resources": {
    "urn:fooapi:widgets": {
      "href": "/widgets/",
      "paging": {          //RFC 5005 5988
        "link": {         
          "rel": "prev",
          "title": "Prev",
          "hreflang": "en",
          "media": "all",
          "charset": "utf-8",
          "type": "application/json",
          "href-template": "{?offset,limit}",
          "href": "?offset=0&limit=10"
        },
        "link": {        
          "rel": "next",
          "title": "Next",
          "hreflang": "en",
          "media": "all",
          "charset": "utf-8",
          "type": "application/json",
          "href-template": "{?offset,limit}",
          "href": "?offset=20&limit=10"
        },
        "link": {        
          "rel": "section",
          "title": "Section",
          "hreflang": "en",
          "media": "all",
          "charset": "utf-8",
          "type": "application/json",
          "href-template": "{?section}",
          "href": "?section=10"
        },
        "start": "http://example.com/start",
        "current": { "href": "./"},
        "last": "http://example.com/last",
        "first": "http://example.com/first"
      },
      "hints": {
        "allow": ["GET", "POST", "PUT", "DELETE"],
        "representations": ["application/json","text/html"],
        "accept-language": ["en"],
        "accept-post": ["application/json"]
      }
    },
    "urn:fooapi:widget": {
      "titles":{
        "default":"The Widgets API", 
        "nl":"Het Widgets API", 
      }, 
      "href-template": "/widgets/{widgetId}",
      "href-vars": {
        "productRoomId": "urn:fooapi:param@widgets"
      },
      "revisions": {        //RFC 5829
        "version-history": "/widgets/{widgetId}/revisions",           
        "latest-version": "/widgets/{widgetId}/latest",               
        "working-copy": "/widgets/{widgetId}/draft",                  
        "working-copy-of": "/widgets/{widgetId}/draft-of" ,           
        "predecessor-version": "/widgets/{widgetId}/prev",         
        "successor-version": "/widgets/{widgetId}/next"              
      },
      "hints": {
        "allow": ["GET", "PUT", "DELETE", "PATCH"],
        "representations": ["application/json", "text/html", "application/json-home"],
        "accept-patch": ["application/json-patch"],
        "accept-put": ["application/json"],
        "accept-ranges": ["bytes"],
        "prefer": ["return-asynch", "return-minimal", "return-representation", "wait", "strict", "lenient"],
        "docs": "http://example.com/docs", // help?? [W3C.REC-html401-19991224](http://www.w3.org/TR/html5/links.html#link-type-help)
        "precondition-req": ["etag", "last-modified"],
        "auth-req": [{ "scheme": "Basic","realms": ["private"]}],
        "status": "development"
      }
    }
  }
}

[mnot]

Cool, thanks!

This makes me think that it'd be interesting to allow links between resources to be expressed in the home doc as well.

Will talk more on the list.