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

From: Dirk F5R <[email-masked]>
Date: Wed, 14 Nov 2012 12:36:57 +0100

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

---

From: Mike Kelly <[email-masked]>
Date: Wed, 14 Nov 2012 14:33:43 +0000

Hi Dirk,

fwiw, I've authored a similar media type (hal+json) that's intended to
be used for more than simply root/home resources.

http://pretty-rfc.herokuapp.com/draft-kelly-json-hal

One company I've discussed hal+json with have asked the same question
about why I did not separate out the linking convention. As a result
of that discussion, I have actually started efforts to extract it and
make them two distinct I-Ds.

Cheers,
M

On Wed, Nov 14, 2012 at 11:36 AM, Dirk F5R <[email-masked]> wrote:
> 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.
>
> 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?
>
> 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.
>
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

-- 
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 15 Nov 2012 11:37:29 +1100

On 14/11/2012, at 10:36 PM, Dirk F5R <[email-masked]> 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.
> 
> 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.

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.

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.

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

Cheers,

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

---

From: Mike Kelly <[email-masked]>
Date: Thu, 15 Nov 2012 09:50:30 +0000

> 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…

RDF made its own life hard by forcing a graph model down into the
data. That is not what HAL is about.

HAL is conventions that allow you to use link relations to identify
the relationships between resources in your application, via outbound
links and containment (aka 'embedded-ness'). The way HAL represents
the state of the resources is just to defer to plain old JSON, there's
no special model for the data. In practice, all HAL really does is add
two reserved properties to the JSON representations you already
expose, namely "_links" and "_embedded".

So for me, it doesn't really make much sense to compare RDF with HAL.
The word count on the JSON-LD spec vs the hal+json spec should say it
all! :)

Cheers,
M

---

From: Graham Klyne <[email-masked]>
Date: Thu, 15 Nov 2012 13:02:53 +0000

> data. That is not what HAL is about.

I don't follow what you're saying here.  I don't disagree (as someone involved 
with RDF) that RDF has made its life hard in several ways, but if what you have 
and want to pass around is a graph, how does one *not* push it down into the data?

(Personally, I'd like to see json-home be something that has a clear mapping to 
RDF, but that's a different discussion.)

#g
--

---

From: Mike Kelly <[email-masked]>
Date: Thu, 15 Nov 2012 13:50:22 +0000

On 15 Nov 2012, at 13:02, Graham Klyne <[email-masked]> wrote:

> I don't follow what you're saying here.  I don't disagree (as someone involved with RDF) that RDF has made its life hard in several ways, but if what you have and want to pass around is a graph, how does one *not* push it down into the data?

Sorry I wasn't clear, I was claiming RDF's problem as a general purpose model is that it assumes what you have and want to pass around is a graph. Most normal people do not have that requirement they are happy with plain old JSON and links between their resources.. so RDF carries a whole load of spec-bloating baggage around with it that a lot of people don't want.

Cheers,
M

---

From: Dirk Fröhner <[email-masked]>
Date: Thu, 15 Nov 2012 17:29:58 +0100

Mark,

thanks for your response. More comments inline.

Glück auf!
Dirk

> 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 hom…
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?
> 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…
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.

---

From: Erik Wilde <[email-masked]>
Date: Thu, 15 Nov 2012 09:36:23 -0800

hello graham.

On 2012-11-15 5:02 , Graham Klyne wrote:
> I don't follow what you're saying here.  I don't disagree (as someone
> involved with RDF) that RDF has made its life hard in several ways, but
> if what you have and want to pass around is a graph, how does one *not*
> push it down into the data?

the big problem with RDF on the level we're discussing here is that RDF 
pushes everything into vocabularies, and thus renders media types almost 
meaningless (apart from distinguishing RDF serializations). that's a 
problem for home documents or similar web-oriented approaches that rely 
on the media type being a crucial signal for understanding the 
interaction semantics of resources.

> (Personally, I'd like to see json-home be something that has a clear
> mapping to RDF, but that's a different discussion.)

fwiw, https://github.com/dret/I-D-1/tree/master/json-home is where i 
have started creating a mapping to XML, and i'd be more than happy to 
collaborate with others to do the same for an RDF schema. but like i 
said above, the whole concept of home documents hinges around the 
assumption that a media type signals interaction semantics, so that 
clients can decide what resources to engage with. in RDF, this is not 
how the world works (yet, i still hope that we'll see this tackled at 
some point in time), so maybe there's a little less utility in the whole 
approach. regardless of that, we have discovered in our current work in 
the "Linked Data Platform" W3C WG that we probably need some concept of 
a "service document" or a "home document", and thus it might be 
interesting to look at how the current json-home approach could be 
mapped to RDF and would give us some useful foundation.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Graham Klyne <[email-masked]>
Date: Thu, 15 Nov 2012 20:30:48 +0000

For information, I've replied to this copying [email-masked] but not 
[email-masked], as I think the discussion is headed into territory more 
germane to web application than general IETF application issues.  Interested 
folks can pick up the discussion at 
http://lists.w3.org/Archives/Public/public-ldp-wg/

#g
--

On 15/11/2012 17:36, Erik Wilde wrote:
> the big problem with RDF on the level we're discussing here is that RDF pushes
> everything into vocabularies, and thus renders media types almost meaningless
> (apart from distinguishing RDF serializations). that's a problem for home
> documents or similar web-oriented approaches that rely on the media type being a
> crucial signal for understanding the interaction semantics of resources.
>
> fwiw, https://github.com/dret/I-D-1/tree/master/json-home is where i have
> started creating a mapping to XML, and i'd be more than happy to collaborate
> with others to do the same for an RDF schema. but like i said above, the whole
> concept of home documents hinges around the assumption that a media type signals
> interaction semantics, so that clients can decide what resources to engage with.
> in RDF, this is not how the world works (yet, i still hope that we'll see this
> tackled at some point in time), so maybe there's a little less utility in the
> whole approach. regardless of that, we have discovered in our current work in
> the "Linked Data Platform" W3C WG that we probably need some concept of a
> "service document" or a "home document", and thus it might be interesting to
> look at how the current json-home approach could be mapped to RDF and would give
> us some useful foundation.
>
> cheers,
>
> dret.
>