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

[Dirk Fröhner <[e-mail]>]

Mark,

thanks for your response. More comments inline.

Glück auf!
Dirk

On 15/11/12 1:37 AM, Mark Nottingham wrote:
> On 14/11/2012, at 10:36 PM, Dirk F5R <[e-mail]> wrote:
>
>> 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?
> Possibly. The thing is, I'm not yet convinced that there's a single style of linking that's right for all uses -- or even a majority of cases -- in JSON, so I haven't tackled this yet. Having a home document seemed to be the low-hanging fruit, and I expect that if we do one day have a predominant way of linking in JSON, we'll converge on that somehow.
Different styles of linking (in JSON) is actually something about which 
we had many discussions in our office during the last months...
> I have talked to Mike about HAL; it may be a contender for enough use cases to be interesting, but I didn't want to tie the fate of this spec to HAL.
...and I would actually be very interested to exchange our results with 
you and Mike - not sure if this should take place exactly here though?
> In the meantime, the links in json-home are interoperable with other serialisations of links (including HAL). The important thing is that the underlying semantics of the link are well-defined, as per RFC5988. The syntax doesn't matter as much (caveat: see below).
>
>
>> 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.
>
> Well, we get concrete benefits when off-the-shelf software can consume a known format; having to relearn every format as you encounter it is expensive (in money, time and effort) and error-prone.
That would mean that off-the-shelf software could consume the API home 
docs but it doesn't necessarily mean that it can consume any other 
representation that comes back when one of the links in the home doc is 
followed. We had something similar in place previously where we were 
kind of forced to employ a resource discovery format (JRD, i.e. XRD for 
JSON) as API home doc and found it very inconvenient to have a different 
format for this. By now we use the same format for API home docs as for 
any other representation that comes back from our APIs. In particular 
this means that we have a consistent way of representing links. But 
maybe I don't completely understand what you have in mind with the 
ability to "scan" API home docs and do stuff with it.
>
> My observation is that coming up with a framework that abstracts out the world into a single format convention is Hard (see: RDF), so I decided to try something more modest here. People intuitively understand "home document."
I'm absolutely with you, I guess it's more a question if that home 
document has to be in a special format. If you compare it with the home 
page of a website, you also wouldn't expect that in a different format 
than any other page that comes from the site.
>
> Cheers,
>
> --
> Mark Nottingham   http://www.mnot.net/
>
>
>