RE: Relating hydra:Classes to hydra:IriTemplates

On 18 Jun 2014 at 12:38, Jindřich Mynarz wrote:
> On Wed, Jun 18, 2014 at 1:29 AM, Markus Lanthaler wrote:
>>> 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/#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

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

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.


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


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

Exactly. That's the difference I had in mind originally because I thought it is necessary that the clients are able to retrieve the class definition. The concept of a separate ApiDocumentation didn't really exist back then and so it perhaps not necessary anymore.


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 18 June 2014 21:13:07 UTC