Re: Relating hydra:Classes to hydra:IriTemplates

Hi,

I was thinking a bit more about relating hydra:Classes to
hydra:IriTemplates. It seems to me that the intended way how to do
that is by using hydra:TemplatedLink to mint a property (like
hydra:search is defined). Consider the following example:

:simple-search-api a hydra:ApiDocumentation ;
  hydra:supportedClass schema:Person .

schema:Person a hydra:Class ;
  :simple-search-person :simple-search-person-template .

:simple-search-person a hydra:TemplatedLink ;
  # Additional possible assertions:
  #   rdfs:domain hydra:Class ;
  #   rdfs:range hydra:IriTemplate ;
  #   rdfs:subPropertyOf hydra:search ;
  hydra:supportedOperation :simple-search-person-operation .

:simple-search-person-operation a hydra:Operation ;
  hydra:method "GET" ;
  hydra:returns schema:Person . # or instead hydra:Collection (of
schema:Persons)?

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

However, this example looks a bit convoluted and the
:simple-search-person-operation seems to be underspecified. I also
thought about relating the hydra:IriTemplate to hydra:Class via
hydra:supportedProperty mechanism. In this way, hydra:property of the
hydra:SupportedProperty would link to a hydra:TemplatedLink, as in the
following example:

schema:Person a hydra:Class ;
  hydra:supportedProperty [
    a hydra:SupportedProperty ;
    hydra:property :simple-search-person
  ] .

:simple-search-person a hydra:TemplatedLink .

If I approach describing the relation in this way, I don't know how to
relate a hydra:IriTemplate to the :simple-search-person templated
link. Is there such a way or is this approach a dead end?

- Jindřich

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

On Mon, Jun 16, 2014 at 10:25 AM, Jindřich Mynarz
<mynarzjindrich@gmail.com> wrote:
> Re-reading Gregg's email, I realized that I misread him with regards
> to the reuse of third-party classes, as he indicated that he's rather
> in favour of reusing third-party classes directly in order to avoid
> proliferation of API-specific subclasses. My bad.
>
> - Jindřich
>
> --
> Jindřich Mynarz
> http://mynarz.net/#jindrich
>
> On Mon, Jun 16, 2014 at 10:17 AM, Jindřich Mynarz
> <mynarzjindrich@gmail.com> wrote:
>> Hi,
>>
>> On Sun, Jun 15, 2014 at 10:26 PM, Markus Lanthaler
>> <markus.lanthaler@gmx.net> wrote:
>>>> 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?
>>
>> 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
>> says, hydra:entrypoint links to "the main entry point of the Web API",
>> which is why I think that if the described simple search functionality
>> was the main (and maybe only) service provided by an API, then it
>> would warrant linking it via hydra:entrypoint from
>> hydra:ApiDocumentation.
>>
>>> 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
>>>       ] .
>>>     ] .
>>
>> I see. 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.
>>
>> I also thought if hydra:ApiDocumentation can also be an entry point,
>> so that the entry point is made self-describing, along these lines:
>>
>> :simple-search-api a hydra:ApiDocumentation ;
>>   hydra:entrypoint :simple-search-api .
>>
>> But then I thought that hydra:ApiDocumentation and the class of
>> resources intended to be used as entry points are probably meant to
>> serve different purposes.
>>
>>>> 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.
>>
>> 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?
>>
>>>> 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.
>>
>> 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?
>>
>>>> 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.
>>
>> 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?
>>
>> I think it may not cause problems if API consumers keep the API
>> description data separate (in a separate named graph if they happen to
>> be using an RDF store), so that local assertions about reused classes
>> don't "leak" into other data and aren't used to produce any inferences
>> when combined with external data. Renaming hydra:Class to
>> hydra:SupportedClass and adding hydra:class property to link to the
>> reused class might also be an option.
>>
>> - Jindřich
>>
>> --
>> Jindřich Mynarz
>> http://mynarz.net/#jindrich

Received on Tuesday, 17 June 2014 10:20:31 UTC