Re: Define Templated supported operations in ApiDocumentation

Hi Aparna

I'm afraid Hydra does not allow to provide any links of any kind
(including templated ones) to resources from API documentation level.
On that level you provide abstracts like supported classes that
defines generic operations executable on resources of those classes.
There is no callable resource described on that level so you could
attach a link to it.
Please remember that API documentation is required to have only an
entry point defined so the client can figure it out where to start
from - initially in earlier specs it was not required at all!

I think an entry point is more suitable for that purpose (section 5.4
IRI template operations should cover it) as this is a callable
resource that you can attach a link to.

There is an option of having API documentation and an entry point
being the same resource, but again when client calls it not in the API
documentation context (i.e. by API discovery link) those generic
concepts are treated as ordinary resources.

Hope it helps.

Karol Szczepanski

wt., 1 mar 2022 o 18:05 Aparna Garimella
<Aparna.Garimella@ihsmarkit.com> napisał(a):
>
> Hello!
>
>
>
> We have been working on developing Semantic APIs using hydra vocabulary and came upon the following situation. We would appreciate your guidance and advice on the vocabulary usage and correctness.
>
>
>
> Issue: How to describe an operation inside the hydra API Documentation to retrieve a single resource based on a templated GET such as:
>
>
>
> GET http://localhost:13973/ExampleResource/{id} that returns a resource of type apiVocab: ExampleResource
>
>
>
> Even though this is an operation on the resource “ExampleResource”, we are having to define it as a hydra:supportedProperty of ExampleResource of type hydra:TemplateLink instead of being able to define it as part of the supportedOperations array.
>
>
>
> Example Resource’s operations
>
> GET /ExampleResource/{id}
> DELETE /ExampleResource/{id}
> POST /ExampleResource
>
>
>
> The IriTemplate is defined inside of the API’s vocabulary as follows:
>
> {
>
>   "@context": {
>
>     "api": http://localhost:13973/vocab/,
>
>     "uv": https://uv.semantic..data/context,
>
>     "xsd": http://www.w3..org/2001/XMLSchema#,
>
>     "jsonld": https://www.w3.org/ns/json-ld#,
>
>     "hydra": https://www.w3.org/ns/hydra/core#,
>
>     "rdfs": http://www.w3.org/2000/01/rdf-schema#,
>
>     "owl": http://www.w3.org/2002/07/owl#,
>
>     "defines": {
>
>       "@reverse": "rdfs:isDefinedBy"
>
>     }
>
>   },
>
>   "@id": http://localhost:13973/vocab,
>
>   "@type": "owl:ontology",
>
>   "defines": [
>
>    {
>
>       "@id": "api:ExampleResourcegetSingleResource",
>
>       "@type": "hydra:IriTemplate",
>
>       "hydra:template": "/{id}",
>
>       "hydra:variableRepresentation": "BasicRepresentation",
>
>       "hydra:mapping": [
>
>         {
>
>           "@type": "hydra:IriTemplateMapping",
>
>           "hydra:variable": "id",
>
>           "hydra:property": "api:ExampleResource#Id",
>
>           "hydra:required": false
>
>         }
>
>       ]
>
>     },
>
> …
>
>
>
> An excerpt of our API Documentation is as follows:
>
> {
>
>   "api": http://localhost:13973/vocab/,
>
>   "@type": "hydra:ApiDocumentation",
>
>   "@id": http://localhost:13973/apidoc,
>
>   "hydra:title": "Example Api",
>
>   "hydra:description": "Example desc",
>
>   "hydra:entrypoint": http://localhost:13973/,
>
>   "hydra:supportedClass": [
>
>     {
>
>       "@id": "api:ExampleResource",
>
>       "@type": "hydra:Class",
>
>       "hydra:description": "ExampleDescription",
>
>       "hydra:supportedProperty": [
>
>         …
>
>          {
>
>           "@id": "api:ExampleResource#getSingleResource",
>
>           "hydra:title": "ExampleResource getSingleResource",
>
>           "@type": "hydra:TemplateLink",
>
>           "rdfs:domain": "api:ExampleResource",
>
>           "rdfs:range": "api:ExampleResourcegetSingleResource",
>
>           "hydra:supportedOperation": {
>
>             "@type": "hydra:Operation",
>
>             "hydra:method": "GET",
>
>             "hydra:expects": "owl:Nothing",
>
>             "hydra:returns": http://localhost:13973/vocab/ExampleResource#
>
>           }
>
>         }
>
>       ],
>
>       "hydra:supportedOperation": [
>
>         {
>
>            "@type": "hydra:Operation",
>
>           "hydra:method": "POST",
>
>           "hydra:title": "Insert Single Resource",
>
>           "hydra:expects": http://localhost:13973/vocab/ExampleResource#,
>
>           "hydra:returns": "owl:Nothing"
>
>         }
>
>       ]
>
>     },
>
>
>
> As illustrated above, we are defining the IriTemplate in API’s vocabulary and defining that as the range for the TemplateLink on the ExampleResource in ApiDocumentation.
>
>
>
> According to the Hydra core vocabulary, hydra:TemplatedLink is a subClassOf rdf:Property and since hydra:supportedProperty has the range of rdf:Property, it seems that TemplatedLinks should be listed with supported properties. However, this means that the Hydra clients must discard TemplateLink supportedProperties when building Http POST requests.
>
>
>
> We would like to confirm if this is the correct way to model the GET single resource operation in the hydra API Documentation. Is there another way to define templated operations?
>
>
>
> Thank you,
>
> Aparna Garimella
>
>
> ________________________________
>
> The information contained in this message is intended only for the recipient, and may be a confidential attorney-client communication or may otherwise be privileged and confidential and protected from disclosure. If the reader of this message is not the intended recipient, or an employee or agent responsible for delivering this message to the intended recipient, please be aware that any dissemination or copying of this communication is strictly prohibited. If you have received this communication in error, please immediately notify us by replying to the message and deleting it from your computer. S&P Global Inc. reserves the right, subject to applicable local law, to monitor, review and process the content of any electronic message or information sent to or from S&P Global Inc. e-mail addresses without informing the sender or recipient of the message. By sending electronic message or information to S&P Global Inc. e-mail addresses you, as the sender, are consenting to S&P Global Inc. processing any of your personal data therein.

Received on Saturday, 5 March 2022 20:10:05 UTC