RE: Define Templated supported operations in ApiDocumentation

Hello Aparna

I’m not sure I understand exactly. From what I see in your original snippets, you are attempting to slightly misuse the concept of a templated link.

Link templates are not an equivalent to “routing” as typically understood by OpenAPI and similar API technologies. In your presented scenario it appears that `ExampleResource` does not need templates at all. The semantics of supporting GET/DELETE are associated with the type `ExampleResource` itself.

POST is slightly unrelated, since it is supported by another type, unnamed in your original email.

Here’s a gist which elaborates: https://gist.github.com/tpluscode/d315b3734b07d81b31f1ad3f2951d2d5

Now, the feature of templates is designed to accommodate client input which is required to construct the target URI. Because the actual target does not have a defined type, the only way for it to support operations is by indirectly attaching them to the predicate. The template does have to be in the resource representations and not API Documentation as mentioned by Karol. In other words, a resource has a property X whose object is a TemplatedLink. That property X supports operations, which means that it will be indirectly supported any object constructed from said template. 
A typical use case is searching, but providing query strings and using `hydra:search` property. In the case of resource creation you are most likely looking at PUT

Here’s another gist as an example: https://gist.github.com/tpluscode/c7ef53816c78bd34284ac39679c0b5a8

Bottom line, by removing the coupling to specific URI structures you can change the URIs of resources at any time (or keep multiple such patterns for different use cases). Your data also becomes much more portable, because the semantics are tied to what the data “is” and not what it “looks like”. This also means that you can rename resources at any time, keeping their semantics on the API level

Best,
Tom


On 7 March 2022 at 17:58:39, Aparna Garimella (aparna.garimella@ihsmarkit.com) wrote:
> 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  
> Sent: Saturday, March 5, 2022 2:09 PM
> To: Aparna Garimella  
> Cc: public-hydra@w3.org; Arthi Kumar  
> 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 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&data=04%7C01%7CAparna.Garimella%40ihsmark  
> > it.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4ac073eab96  
> > da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC  
> > 4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000&sd  
> > ata=336TyPnziZtVjJXZJUPHX%2FO3A7D%2Fq%2F8s1dd%2BW3IQnYw%3D&reserve  
> > d=0,
> >
> > "hydra":
> > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.  
> > w3.org%2Fns%2Fhydra%2Fcore%23&data=04%7C01%7CAparna.Garimella%40ih  
> > smarkit.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4ac073  
> > eab96da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8eyJWI  
> > joiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000&a  
> > mp;sdata=05HNycje6taRXx7dBN9izTi2YN6a6Ac9PD8CT6cDxeA%3D&reserved=0  
> > ,
> >
> > "rdfs":
> > https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w  
> > 3.org%2F2000%2F01%2Frdf-schema%23&data=04%7C01%7CAparna.Garimella%  
> > 40ihsmarkit.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4a  
> > c073eab96da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8e  
> > yJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C20  
> > 00&sdata=TXQ3lBAxG68Rm7P4%2BD7v%2B4ZkMgbeGiDkddwkrYDqMyM%3D&re  
> > served=0,
> >
> > "owl":
> > https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w  
> > 3.org%2F2002%2F07%2Fowl%23&data=04%7C01%7CAparna.Garimella%40ihsma  
> > rkit.com%7C69040f40d9ce4db8ef2108d9fee3faba%7Cc1156c2fa3bb4fc4ac073eab  
> > 96da8d10%7C0%7C0%7C637821077545887845%7CUnknown%7CTWFpbGZsb3d8eyJWIjoi  
> > MC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000&  
> > sdata=GMe5Ijggu07QpRf8tw393F84vPW6q%2F6aLJEVVmYIvFg%3D&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 Tuesday, 8 March 2022 08:56:51 UTC