RE: Relating hydra:Classes to hydra:IriTemplates

On  Sunday, June 15, 2014 6:51 PM, Jindřich Mynarz wrote:
> in the interest of keeping distinct topics in separate threads, I'll
> continue with my questions about Hydra in another email.

Great. In future, please try to send plain-text mails instead of HTML mails. Thanks!


> Overall, I struggle to understand the connections between several
> parts of the Hydra Core Vocabulary. The "main" part of the vocabulary,
> including hydra:Class, hydra:SupportedProperty and hydra:Operation, is
> well-described and fits nicely most CRUD scenarios. However, I find it
> difficult to grasp how it's related with the part including
> hydra:TemplatedLink or hydra:IriTemplate, which seem to match more
> search-oriented scenarios.

Yeah, they are a bit detached and probably underspecified at the moment but you are right, they are mostly for search-related use cases.


> I was thinking about describing a simple search API in Hydra. I
> started with a description of an API that allows to search for
> resources regardless of their type via free-text queries. I found out
> that Hydra allows to link to hydra:IriTemplate from
> hydra:ApiDocumentation via hydra:entrypoint:

How did you find that out? I assume you saw that the range of entrypoint is hydra:Resource and that a IriTemplate is a subclass of hydra:Resource, right?


> :simple-search-api a hydra:ApiDocumentation ;
>   hydra:entrypoint :simple-search .
> 
> :simple-search a hydra:IriTemplate ;
>   hydra:template "/search{?q}" ;
>   hydra:mapping [
>       a hydra:IriTemplateMapping ;
>       hydra:variable "q" ;
>       hydra:property hydra:freetextQuery ;
>       hydra:required true
>     ] .
> 
> Is this description in line with how Hydra is intended to be used? Or
> is it a wrong interpretation of Hydra's spec?

It's not really how I intended it to be used. The entrypoint property is there to point to, well, the API's main entry point. Think of it as the home link that you can find on almost any website. In that spirit, you would rather do something like this:

  :simple-search-api a hydra:ApiDocumentation ;
    hydra:entrypoint </> .
  
  </> hydra:search [
    a hydra:IriTemplate ;
    hydra:template "/search{?q}" ;
    hydra:mapping [
        a hydra:IriTemplateMapping ;
        hydra:variable "q" ;
        hydra:property hydra:freetextQuery ;
        hydra:required true
      ] .
    ] .


> Then I thought how to describe a similar simple search but restricted
> to instances of a specified class. I assume this can be done via
> hydra:supportedClass. For example, if an API offers a search for
> instances schema:Person, then I presume schema:Person can be described
> as hydra:supportedClass:
> 
> :simple-search-api a hydra:ApiDocumentation ;
>   hydra:supportedClass schema:Person .

Sure, you can state this. But it doesn't restrict the query to instances of that class.


> Now, what I don't understand is the preferred way of connecting
> hydra:search (or any hydra:TemplatedLink) to the supported Person
> class (or any hydra:Class). Can I use hydra:search directly with
> supported classes of the API, such as in the following example?
> 
> :SimpleSearchPerson hydra:search :simple-search-person-template .
> 
> :simple-search-person-template a hydra:IriTemplate ;
>   hydra:template "/person{?name}" ;
>   hydra:mapping [
>       a hydra:IriTemplateMapping ;
>       hydra:variable "name" ;
>       hydra:property schema:name ;
>       hydra:required true
>     ] .
> 
> Or instead, is it necessary to attach :simple-search-person-template
> to :SimpleSearchPerson through hydra:supportedOperation? Relating
> hydra:Classes to hydra:IriTemplates is probably the part which is the
> most unclear to me.

I would model this by creating a collection containing persons and then attaching :simple-search-person-template via hydra:search to that collection.


> However, then I wondered if it's correct to reuse schema:Person
> directly and attach to it API-specific hydra:Operations. Is it better
> to define an API-specific subclass of the extended class, to which
> operations are attached? This seems to be a better approach, since the
> API likely doesn't support all instances of schema:Person, but only an
> API-specific subset of schema:Persons.

Yeah, generally speaking it is better to model things this way.


> :simple-search-api a hydra:ApiDocumentation ;
>   hydra:supportedClass :SimpleSearchPerson .
> 
> :SimpleSearchPerson a hydra:Class ;
>   rdfs:subClassOf schema:Person .
> 
> Is this a recommended approach in Hydra how to reuse third-party
> vocabularies and extend them with local assertions?

We haven't decided that yet. Local assertions are easier to understand and use but pollute everyone's data if you are not careful. It is a trade-off. An alternative would be to use a similar pattern as the one we use with SupportedProperty.


Hope this clarifies some things,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Sunday, 15 June 2014 20:26:44 UTC