RE: Discovering Hydra API by dereferencing

On 9 Jul 2014 at 22:22, Tomasz Pluskiewicz wrote:
> On JSON-LD list you wrote:
> 
> Yeah, to really get every possible operation and link, you would need to
> reference all of them. I'm still a bit on the fence about that because
> it is extremely inefficient in most cases. I was thinking about adding a
> statement to the spec that basically requires all links and operations
> to be declared either in the ApiDocumentation or inline so that there
> are only those two places for a client to look at. Of course people can
> place information also directly in vocabularies but then it wouldn't be
> guaranteed that those things are discovered *unless* they are also
> referenced by a apiDocumentation HTTP Link header.

It was also sent to this list:

  http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0046.html


> I'm conerned about (object) properties, which are not links. They will
> most likely make up for most of the resources. I guess it wouldn't be
> wise to try to dereference each one of them to see whether they are
> typed as hydra:Links. Or would it?

No probably not. This is something that should be discussed in the context of ISSUE-59 [1] I think. It would be much more efficient to enumerate the properties that are links in the ApiDocumentation instead of having to dereference all of them.


> Hm, and you also consider an idea that Hydra clients should not
> actually dereference classes but only the ApiDocumentation, declared
> in HTTP header?

Yeah very much for the same reasons.


> Lastly what has just occured to me is that the ApiDocumentation would
> have to be dereferenced at every request, is that right? Due to its
> dynamic nature.

The server can and should declare the ApiDocumentation to be cacheable. This is really similar to CSS stylesheets for example. It would be very inefficient to download it again for every single page you are accessing even though it *might* change at any point. A common pattern is thus to cache it for a very long time (e.g. a year) and, if it really changes, simply change its URL (styles-20140320.css -> styles-20140710.css). Exactly the same mechanisms can be used for ApiDocumentations.


[1] https://github.com/HydraCG/Specifications/issues/59


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 10 July 2014 11:40:16 UTC