[apps-discuss] json-home: comments and questions on draft 02

[Dirk F5R <[e-mail]>]

Hi all, hi Mark,

I had a closer look at 
http://pretty-rfc.herokuapp.com/draft-nottingham-json-home and 
http://tools.ietf.org/html/draft-nottingham-json-home-02 since I also 
absolutely see the need for an API "home page" as well. As a matter of 
fact, the specs I have contributed to at work come with what we call a 
"service document" (I can't help using that term in the remainder of 
this mail). This is only another term for basically the same concept: 
one single entry point into a hypermedia API that reveals links to 
something like top-level resources. The URI to the service document is 
the only thing that needs to be published to client developers, from 
there we strictly follow the HATEOAS principle.

I have a few comments / questions on json-home:

When I look at the json-home draft, it looks to me as if it were 
actually two separate ones. One that deals with the need of a service 
document and how it might look like and one that defines how links 
should look like in JSON. The latter one though is nothing specific to 
the service document but would rather be a general convention. Shouldn't 
this be two separate draft documents?

As to my current perception, I'm also not sure why the service document 
should have a different format or structure than any other document that 
comes back from an API. For instance, if your representations always 
come with an attribute called "links" that hosts explicit links by 
relation types, why should this be different for the service document? 
This leads me to the opinion that it should be defined <somewhere> as a 
requirement that hypermedia APIs must come with a service document but I 
don't necessarily see the need to define a particular format or media 
type for it.

Thanks for listening and happy to read your comments. ;-)

Glück auf!
Dirk