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