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