RE: Define Templated supported operations in ApiDocumentation

Hi Karol,

Thank you for the response!

As you mentioned section 5.4, it specifies how to attach a supportedOperation to a property that connects a subject of a relation with its IRI template. This is where the question is. I would like to model the single GET request that has a route template as an operation on the resource (supportedOperation on supportedClass) instead of as a supportedOperation linked to the TemplateLink type property of that supportedClass. The ExampleResource described below is a supported class and has some supportedProperties. If supportedOperations are used to describe the affordances of a Resource, it seems that a templated operation (like GET /ExampleResource/{id}) should be defined as a supportedOperation with a template (and associated mappings). Can this be done or are these types of request templates implied? If they are, I wonder how a search request on a collection Resource with query parameters can be modeled as an affordance vs a Link property. Looking forward to hearing your thoughts.

Thank you,
Aparna


-----Original Message-----
From: Karol Szczepański <karol.szczepanski@gmail.com>
Sent: Saturday, March 5, 2022 2:09 PM
To: Aparna Garimella <Aparna.Garimella@ihsmarkit.com>
Cc: public-hydra@w3.org; Arthi Kumar <Arthi.Kumar@ihsmarkit.com>
Subject: Re: Define Templated supported operations in ApiDocumentation

[CAUTION] EXTERNAL EMAIL ..


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://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.
> w3.org%2Fns%2Fjson-ld%23&amp;data=04%7C01%7CAparna.Garimella%40ihsmark
> it.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4ac073eab96
> da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC
> 4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000&amp;sd
> ata=336TyPnziZtVjJXZJUPHX%2FO3A7D%2Fq%2F8s1dd%2BW3IQnYw%3D&amp;reserve
> d=0,
>
>     "hydra":
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.
> w3.org%2Fns%2Fhydra%2Fcore%23&amp;data=04%7C01%7CAparna.Garimella%40ih
> smarkit.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4ac073
> eab96da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8eyJWI
> joiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000&a
> mp;sdata=05HNycje6taRXx7dBN9izTi2YN6a6Ac9PD8CT6cDxeA%3D&amp;reserved=0
> ,
>
>     "rdfs":
> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w
> 3.org%2F2000%2F01%2Frdf-schema%23&amp;data=04%7C01%7CAparna.Garimella%
> 40ihsmarkit.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4a
> c073eab96da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8e
> yJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C20
> 00&amp;sdata=TXQ3lBAxG68Rm7P4%2BD7v%2B4ZkMgbeGiDkddwkrYDqMyM%3D&amp;re
> served=0,
>
>     "owl":
> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w
> 3.org%2F2002%2F07%2Fowl%23&amp;data=04%7C01%7CAparna.Garimella%40ihsma
> rkit.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4ac073eab
> 96da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8eyJWIjoi
> MC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000&amp;
> sdata=GMe5Ijggu07QpRf8tw393F84vPW6q%2F6aLJEVVmYIvFg%3D&amp;reserved=0,
>
>     "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.

________________________________

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 Monday, 7 March 2022 16:57:50 UTC