Discovering IriTemplate and others

tpluscode commented 4 years ago

Description

I have been discussing with @bergos recently the usage of IriTemplate and TemplatedLink.

How I thought about them

I have always only considered the template to be directly attached to the link in question. Take a link to lookup (or create) a resource by appending a slug. Let it be a Person

</people>
  a hydra:Collection ;
  api:personByName [
    a hydra:IriTemplate ;
    hydra:template "/people/{name}"
  ]

Where obviously api:personByName a hydra:TemplatedLink .

How @bergos thinks about them

It never occurred to me however that the occurrence of hydra:IriTemplate could also be placed in the ApiDocumentation graph.

</people>
  a hydra:Collection ;
  api:personByName api:PersonByNameTemplate .

And in the api documentation resource a client would find api:PersonByNameTemplate defined as above.

While not technically forbidden, the spec is not explicit here either, is it? I think it totally makes to make it clear that any Hydra term which is valid in the resource, might also be only referenced and the client should look for it in the Api Documentation to find more about it.

bergos commented 4 years ago

Thanks for creating the issues!

Some thoughts about the conflict I always felt when I had to put the template either into the resource data or API documentation and why #207 together with #208 could fix it:

Besides the IriTemplates, everything in Hydra can be separated very well in resource data and API documentation. IriTemplates don't fit into only one of the two categories. The template contains the IRI of the resource, so it's somehow connected to the resource. But the benefit of the template data comes from using the API. Therefore the question is can it be shifted in one or the other direction? Using the template without using the API will not work. Shifting it towards the API documentation direction could work if it would be possible to remove the resource part of the IRI. Reducing the template to a relative part and resolve the full IRI with the resource IRI, could fix that problem. Then we would have a clear separation: The resource IRI comes from the resource data and the variable part comes from the API documentation.

alien-mcl commented 4 years ago

Ok - this looks like a thing that could be put in the specification as a separate paragraph.

I think we may end up with something defining how a client should behave in these circumstances:

in case of an a right hand side related resource is not defined and it is supposed to be an IriTemplate, client SHOULD look in the API documentation for definition
in case it is still undefined and the host name of the URL (not IRI!) of this resource matches the host name of the obtained document, client SHOULD dereference that URL and look for for definition
in case it is still undefined client SHOULD either ignore (i.e. for display purspose) or throw an exception (i.e. operation is about to be executed)

alien-mcl commented 3 years ago

PR #209 should have this issue solved - closing

HydraCG / Specifications