- From: Jindřich Mynarz <mynarzjindrich@gmail.com>
- Date: Thu, 19 Jun 2014 12:04:42 +0200
- To: public-hydra@w3.org
On Wed, Jun 18, 2014 at 11:12 PM, Markus Lanthaler <markus.lanthaler@gmx.net> wrote: >> Nothing particularly bright comes to my mind, but maybe a sentence like >> "An entry point is a dereferenceable resource that provides links to >> access the API." can be added after the first sentence of the section >> 4.3 >> (http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered >> - web-api). > > Hmm... honestly I find this a bit confusing. It gives the impression that an entry point is some intermediary node between the API documentation and the API itself. That's however not true. It is already part of the API. Actually, I find the spec is already quite clear about it: > > "The first step when trying to access a Web API is to find an entry point..." > > Do other people find the concept of an entry point difficult to understand? What about the description thereof in the specification? > > http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered-web-api Well, as I said in my previous email, I don't find the description I've provided to be particularly well-phrase. Let's look at it this way. The rdfs:range of hydra:entrypoint is defined to be hydra:Resource. Hydra describes several sub-classes of hydra:Resource: hydra:ApiDocumentation hydra:Collection hydra:IriTemplate hydra:IriTemplateMapping hydra:Operation hydra:StatusCodeDescription hydra:SupportedProperty Judging just from the RDF description of Hydra, each of these sub-classes can be used in the range of hydra:entrypoint, however, it clearly doesn't make sense to do so for several of these sub-classes (e.g., hydra:IriTemplateMapping). Further disambiguation is thus left to the description in Hydra's specification, where I can't find any suggestion what classes are typically used as entry points. The reader is left wondering if for instance hydra:IriTemplate or hydra:Collection are fine to be used as API entry points. I think that even better than describing it in plain-text would be to have at least one example in the shape: :api-documentation a hydra:ApiDocumentation ; hydra:entrypoint :entry-point . :entry-point a :Class . Where :Class would be an example of recommended class for an entry point. >> If you don't embed the </users/> hydra:Collection in the </> resource, >> then you'd still need to dereference it first to discover that offers >> a search functionality. > > Yes, but is it a problem to embed it there? I do understand that you might want to keep this cleaner. I just want to understand whether there are any technical drawbacks. No, I don't see any technical drawbacks of embedding the descriptions of collections directly in an API entry point. The only drawback is duplication of the description of collection in the representation of entry point and its own representation. >> I'd rather have a way to enable clients to >> discover such functionality (also) via hydra:ApiDocumentation and >> hydra:supportedClass. Is the following pattern, which I have used in >> my previous questions as well, violating some assumptions in Hydra? >> >> :api-documentation a hydra:ApiDocumentation ; >> hydra:supportedClass :Class . >> :Class hydra:search :search-iri-template . > > No, but it is currently undefined how a client should interpret that information. I have to say, I quite like this idea even though it might promote tight coupling. Why do you think it might promote tight coupling in contrast to the other approaches? - Jindřich -- Jindřich Mynarz http://mynarz
Received on Thursday, 19 June 2014 10:05:31 UTC