RE: JSON-LD / Hydra Console - Entry Point seems not to be correct

On 18 Mai 2015 at 08:45, Tobias Zahn wrote:
> Coming back to the description again: I thought (but I am not sure
> anymore after reading your reply), that the documentation displayed
> (e.g. for EntryPoint) would be loaded in this way: 1)
> http://www.markus-lanthaler.com/hydra/api-demo/ is loaded and parsed 2)
> http://www.markus-lanthaler.com/hydra/api-demo/contexts/EntryPoint.jsonld
>  is loaded and parsed in order to dereference EntryPoint and other types
> 3) As the EntryPoint is specified as vocab:entryPoint in
> EntryPoint.jsonld, we need to load the vocab as well... 4)
> http://www.markus-lanthaler.com/hydra/api-demo/vocab# is loaded 5) Now
> we can dereference the EntryPoint from 1) and display the documentation
> for this type.

That's how it used to work. I changed it a while ago because it turned out that in practice
  - blindly (trying to) dereference all used vocabularies is impractical
  - the "style" of things like property labels varies wildly between vocabularies which leads to a bad user experience
  - developers usually want to have more control on what documentation is displayed

Thus, the HydraConsole now
 1) loads /hydra/api-demo/
 2) it loads the referenced context hydra/api-demo/contexts/EntryPoint.jsonld in order to process the JSON-LD retrieved in 1)
 3) the Hydra ApiDocumentation referenced in the HTTP header [1] that is part of the response to 1) is loaded
 4) the documentation is generated out of that hydra:ApiDocumentation (mainly hydra:title and hydra:description)


> Am 17.05.2015 um 20:48 schrieb Markus Lanthaler:
>> The HydraConsole doesn't load the vocab (anymore). It relies on the
>> data (hydra:title, hydra:description) in the Hydra ApiDocumentation.
> 
> Now what you are telling me is that the documentation actually comes
> from http://www.w3.org/ns/hydra/core# - but how?

No, 

  curl http://www.markus-lanthaler.com/hydra/event-api/  -i

returns

  HTTP/1.1 200 OK
  ...
  Link: < <http://www.markus-lanthaler.com/hydra/event-api/vocab>;
             rel="http://www.w3.org/ns/hydra/core#apiDocumentation"

so it is loaded from http://www.markus-lanthaler.com/hydra/event-api/vocab. I really should change that to be /apidoc or something. The vocabulary in this case is schema.org. The reason it is vocabulary is that originally I returned both the vocabulary and the API documentation in a single file (and both were auto-generated). 

Does this make it any clearer? Have you read the relevant section [1] in the spec?


Cheers,
Markus


[1] http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered-web-api


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 21 May 2015 21:12:47 UTC