Subject: Expanding the definition of 'service' link relation type to cover 'Home Documents'

From: Jan Algermissen <[email-masked]>
Date: Sun, 17 Feb 2013 11:31:46 +0100

Mark et al,

I think it would make sense to expand the definition of the 'service' link relation type[1] to cover JSON Home[2] documents.

Then 'service' could be used to point to the home document from within representations served from a given API. Much like most Web pages of a given Web site include the top menu of the site.

When I am being given a bookmark into an API, dereferencing that bookmark would enable me to find the home document without knowing the API's 'main' entry URI.

GET /products/42
...

200 Ok
Link: </home>;rel="service";title="API Home Document"
...

GET /home
Accept: application/json-home
...

I suggest rewording the definition to something like

"Indicates a URI that can be used to retrieve a service- *or home* document *that enables discovery of resources of a service or Web API*"

Thoughts?

Jan

[1] http://www.iana.org/assignments/link-relations/link-relations.xml
[2] http://tools.ietf.org/html/draft-nottingham-json-home-02

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 18 Feb 2013 14:30:46 +1100

That could work. My big concern is that you'd confuse consumers who think that service implies the use of APP. Using the type parameter will help, of course.

James, what do you think?

Probably worth asking on the atom list(s) too...

--
Mark Nottingham   http://www.mnot.net/