Re: Relating hydra:Classes to hydra:IriTemplates

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