Re: Relating hydra:Classes to hydra:IriTemplates

On Wed, Jun 18, 2014 at 1:29 AM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
>> Yes. I was thinking that it's likely not how hydra:entrypoint was
>> intended to be used, but since it's rdfs:range is set to generic
>> hydra:Resource, I thought it's permissible. As the Hydra specification
>
> It's certainly not forbidden. The question however is if clients would reasonably be able to understand it given that if you link to the IRI template directly, you lose the information that it can be used to query something (the whole API?).

Exactly. I believe attaching hydra:IriTemplate via hydra:search
directly to hydra:entrypoint is appropriate if it's for example a
simple full-text search of the whole API.


> If such a thing is common (I don't know), using hydra:search on hydra:ApiDocumentation would be better IMO. But that's ambiguous as well since it could also be interpreted as queriny the ApiDocumentation itself. So I think the best design is still to model it like this:
>
>    </apidoc> hydra:entrypoint [ hydra:search { IRI template } ] .

Yes, it's likely better to keep hydra:ApiDocumentation and entry point
as distinct resources as they serve different purposes.


>> It might be that I've omitted the root (</>) resource linked
>> via hydra:entrypoint because the Hydra vocabulary doesn't have an
>> explicit concept of an entry point, such as schema:EntryPoint. I don't
>> think there necessarily needs to be such concept in Hydra, but a
>> little more guidance in the specification as to what is the intended
>> rdfs:range of hydra:entrypoint would help.
>
> Yeah, that's probably a good idea. Do you have some concrete wording in mind?

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/#h3_discovering-a-hydra-powered-web-api).

(The description of <http://schema.org/EntryPoint> isn't very helpful here.)


>> So if I wanted to hint that HTTP GET of the search hydra:IriTemplate
>> returns a hydra:Collection of schema:Person, I'd need to use
>> hydra:returns schema:Person instead? How would I use hydra:returns
>> with a hydra:IriTemplate?
>
> That's currently undefined. There have been discussions in the past about removing hydra:returns altogether as it might promote tight coupling. So we haven't really discussed yet to allow it on other things such a IriTemplate as well. But it would definitely make sense IMO. I've create ISSUE-50 [1] to track this. It's already quite late. I'll improve the description later.

If hydra:returns is defined as providing a hint, rather than
prescribing the class of the returned instances, then I think it may
improve the API documentation rather than guide developers to write
tightly coupled clients.


>> How would a client discover search functionality described in this way
>> without first dereferencing the collection containing persons? How
>> would you describe it in hydra:ApiDocumentation or link it from an
>> entry point?
>
> Using a couple of things which aren't in the vocabulary yet but have been discussed recently (in JSON-LD as I think it makes the document boundaries clearer in this case):
>
>   {
>     "@id": "/",
>     "@type": "EntryPoint",
>     "collection": {
>       "@id": "/users/",
>       "@type": "Collection",
>       "manages": {
>         "property": "rdf:type",
>         "object": "schema:Person"
>       }
>       "search": {
>         "@type": "IriTemplate",
>         ...
>       }
>     }
>   }

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


>> So both you and Gregg (as indicated in his mail in this thread) are in
>> favour of not reusing third-party classes directly, but rather minting
>> their API-specific subclasses?
>
> No, I didn't say I'm in favor of that. Actually I'm still on the fence about this :-) I don't like the introduction of subclasses but am also a bit worried about the "pollution". Perhaps using a pattern similar to SupportedProperty might be best. I'm not sure.

Having a hydra:SupportedClass might be an option to describe local
semantics of class instances. What is the key difference between
hydra:Class and rdfs:Class anyway? Is it that hydra:Classes should be
all dereferenceable?


> I'll reply to the other mails tomorrow and call it a day now :-)

No problem, thanks for your responses.

- Jindřich

-- 
Jindřich Mynarz
http://mynarz.net/#jindrich

Received on Wednesday, 18 June 2014 10:39:15 UTC