RE: Relating hydra:Classes to hydra:IriTemplates

On 16 Jun 2014 at 10:17, Jindřich Mynarz wrote: 
> On Sun, Jun 15, 2014 at 10:26 PM, Markus Lanthaler 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

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


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

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


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


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

Yeah, they serve different purposes. You could, however, design an API without an ApiDocumentation if you want. Just include all necessary information directly in the API responses.


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

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.


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

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",
        ...
      }
    }
  }


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

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.


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


Cheers,
Markus


[1] https://github.com/HydraCG/Specifications/issues/50


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 17 June 2014 23:30:08 UTC