Relating hydra:Classes to hydra:IriTemplates

Hi,

in the interest of keeping distinct topics in separate threads, I'll
continue with my questions about Hydra in another email.

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.

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:

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

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 .

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.

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

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.

Best,

Jindřich

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