RE: hydra:supportedOperation and hydra:IriTemplate

Hi Christopher,

So, if I understood you correctly, you want to browse a collection of items and also efficiently access subsets or specific items of that collection.

There are multiple ways to achieve that depending on what you want to optimize for. One is filtering the collection. That is unfortunately not fully specified yet. We couldn't reach consensus before the summer break (see [1-2]). This would be a good opportunity to reopen those discussions.

The alternative would be to either mint a separate property (aka link relation type) that makes the intent of the IRI template clear or specialize, i.e., subclass, hydra:Operation.

Does that answer your question?


Cheers,
Markus


[1] https://github.com/HydraCG/Specifications/issues/45
[2] https://www.w3.org/community/hydra/wiki/Filtering


--
Markus Lanthaler
@markuslanthaler



--------------- Original message ----------------
From: Christopher Johnson [mailto:chjohnson39@gmail.com] 
Sent: Tuesday, November 8, 2016 11:11 AM
To: Markus Lanthaler <markus.lanthaler@gmx.net>
Cc: public-hydra@w3.org
Subject: Re: hydra:supportedOperation and hydra:IriTemplate

Hi Markus,

Thank you for the reply.  I try to explain the context of this API use case in more general terms first.  The use case of this API is to generify the publishing endpoints of IIIF Manifest Collections, which are now predominantly published as "hard links".  I think that this may be a good fit for a HATEOAS enabled API on the server side, preferably with the Hydra Core Vocabulary.  A generic "collection browser" client (i.e. one that is not hard wired to particular resource URI definitions) would then be much easier to develop.

The API could serve both criteria (TemplatedLink) and generic requests where a generic request would respond with all resource nodes for that class request type.  So, if the client wanted all sc:Manifest it would just ask the entryPoint  "GET sc:Manifest" and the server would do the dereferencing (that routes it to a "canned" SPARQL query like http://service.b-ol.de/api/graphs/manifests.nt) .  

Alternatively, if the client wants a specific sc:Manifest, it would establish from the apiDocumentation example TemplatedLink class that a different "template specific" operation method (e.g. GETT sc:Manifest) requires a a parameter (e.g. http://service.b-ol.de/api/graphs/manifest.nt?node={node}).  What I have done, (that works, but is not optimal) as previously mentioned is to do a type check on "expects" for that operation.  If the operation expects an IriTemplate, then the httpClient knows to substitute the parsedLink for the template @id in the final request.

This is why I am trying to understand if there is an established (or normative) practice where the server can define a unique supportedOperation method (or type check) for TemplateIri type requests, so that the client can decide if to implement template parsing and how exactly to pass the parsed template link back to httpClient.

I hope this is clear!

Cheers,
Christopher

On 7 November 2016 at 21:34, Markus Lanthaler <mailto:markus.lanthaler@gmx.net> wrote:
Hi Christopher,

On Sunday, November 6, 2016 7:40 PM, Christopher Johnson wrote:
> Hello list,
>
> I am trying to build an hydra-core enabled API that handles
> IriTemplates.  I apologize in advance if the following is out of your
> normal topic scope or is too specific..

Any kind of questions related to Hydra are very welcome on this list. I have to admit though, that I have troubles understanding yours :-) Could you please explain what you would like to achieve resp. what you would like to describe in Hydra? Or are you asking how a client implementation is supposed to deal with the JSON-LD below?

Btw. could you please join the Hydra W3C Community Group. Details can be found at

  http://www.hydra-cg.com/#community


>  I should preface that I have
> modified the hydra-core javascript implementation to work for my use
> case.
>
> I have a few questions regarding norms for defining supportedOperation
> method and expected for an TemplatedLink property in the
> apiDocumentation.
>
> I have constructed the following procedure:
> 1) loadDocument
> 2) find declared TemplatedLink property supported operation in document
> properties.
> 3) find TemplatedLink property class with the api
> 4) define the templated link from the TemplatedLink class template property
> 4) parse the template link with expected variable(s).  (I am using
> uri-templates to do this).
> 5) invoke supported operation method and pass parsed templated link a
>  content.
> 6) have httpClient.rawInvoke check if expected is IriTemplate class, and
> if so, set url = content.
>
> Step #6 is where my questions arise.  Is there a convention for an
> expected template type check or supportedOperation method for template
> requests by httpClient?  Should IriTemplate be declared as a
> hydra:Class or something else in the apiDocumentation?  (It seems that
> only hydra:Class classes can be declared as "expected".)  Also, since
> I did not want to use a domain specific IriTemplate class check in the
> core client, I have reinstantiated the core class in my api, which is
> probably not correct.
>
> For reference, here is part of the apiDocumentation for the above:
>   "supportedClass": [
>     {
>       "@id": "http://service.b-ol.de/api/hydra.json#EntryPoint",
>        {...}
>       "supportedProperty": [
>         {
>           "property": {
>             "@id": "http://iiif.io/api/presentation/2#Manifest",
>             "@type": "TemplatedLink",
>             "http://www..http://w3.org/2000/01/rdf-schema#label": "IIIF Manifest",
>             "domain": "http://service.b-ol.de/api/hydra.json#EntryPoint",
>             "range": "Resource",
>             "supportedOperation": [
>               {
>                 "@id": "http://iiif.io/api/presentation/2#Manifest/GET",
>                 "@type": "Operation",
>                 "expects": "http://www.w3.org/ns/hydra/core#IriTemplate",
>                 "method": "GET",
>                 "http://www.w3.org/2000/01/rdf-schema#label": "Retrieves a Manifest Resource",
>                 "returns": "http://www.w3.org/ns/hydra/core#Resource"
>               }
>             ]
>           }
>         }
>        ]
>     },
>     {
>       "@id": "http://iiif.io/api/presentation/2#Manifest",
>       "@type": "Class",
>       "template": "http://service.b-ol.de/api/graphs/manifest.nt?node={node}",
>       "http://www.w3.org/2000/01/rdf-schema#comment": "A IIIF Manifest",
>       "http://www.w3..org/2000/01/rdf-schema#label": "Manifest",
>       "supportedOperation": {
>         "@id": "http://service.b-ol.de/api/hydra.json#EntryPoint/GET",
>         "@type": "Operation",
>         "http://www.w3.org/2000/01/rdf-schema#label": "The APIs main entry point.",
>         "method": "GET",
>         "returns": {
>           "@id": "http://iiif.io/api/presentation/2#Manifest"
>         },
>         "statusCodes": []
>       }
>     },
>     {
>       "@id": "http://www.w3.org/ns/hydra/core#IriTemplate",
>       "@type": "Class",
>       "template": "http://service.b-ol.de/api/hydra.json#EntryPoint/graphs/{query}?node={node}",
>       "variableRepresentation": "BasicRepresentation",
>       "mapping": [
>         {
>           "@type": "IriTemplateMapping",
>           "variable": "query",
>           "required": false
>         },
>         {
>           "@type": "IriTemplateMapping",
>           "variable": "node",
>           "required": true
>         }
>       ]
>     }
> ]
>
> Thanks for your assistance,
> Christopher Johnson


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 8 November 2016 19:26:47 UTC