- From: Aparna Garimella <Aparna.Garimella@ihsmarkit.com>
- Date: Tue, 1 Mar 2022 17:01:40 +0000
- To: "public-hydra@w3.org" <public-hydra@w3.org>
- CC: Arthi Kumar <Arthi.Kumar@ihsmarkit.com>
- Message-ID: <BY5PR12MB4033CF7DA749D6AE320813A098029@BY5PR12MB4033.namprd12.prod.outlook.com>
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}<http://localhost:13973/ExampleResource/%7bid%7d> 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
1. GET /ExampleResource/{id}
2. DELETE /ExampleResource/{id}
3. 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<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fuv.semantic.data%2Fcontext&data=04%7C01%7CAparna.Garimella%40ihsmarkit.com%7Cf4a7cce01c1f4fd942aa08d9fba413c4%7Cc1156c2fa3bb4fc4ac073eab96da8d10%7C0%7C0%7C637817504392468912%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=xlYx5od6hoMX%2FwIxAldGu9g1N6%2FrFL0aBMof1mXihfI%3D&reserved=0>,
"xsd": http://www.w3.org/2001/XMLSchema#<https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%23&data=04%7C01%7CAparna.Garimella%40ihsmarkit.com%7Cf4a7cce01c1f4fd942aa08d9fba413c4%7Cc1156c2fa3bb4fc4ac073eab96da8d10%7C0%7C0%7C637817504392468912%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=57hWow7WyikDrTvUcg5U%2FdwMwqeyiTQn5m5ABC6X%2BTQ%3D&reserved=0>,
"jsonld": https://www.w3.org/ns/json-ld#<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.w3.org%2Fns%2Fjson-ld%23&data=04%7C01%7CAparna.Garimella%40ihsmarkit.com%7Cf4a7cce01c1f4fd942aa08d9fba413c4%7Cc1156c2fa3bb4fc4ac073eab96da8d10%7C0%7C0%7C637817504392468912%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=x7d43HZ1jM85XyzMKL1tJA0NB1jEpi5C7XQnOtVzM4U%3D&reserved=0>,
"hydra": https://www.w3.org/ns/hydra/core#<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.w3.org%2Fns%2Fhydra%2Fcore%23&data=04%7C01%7CAparna.Garimella%40ihsmarkit.com%7Cf4a7cce01c1f4fd942aa08d9fba413c4%7Cc1156c2fa3bb4fc4ac073eab96da8d10%7C0%7C0%7C637817504392468912%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=GsGRYVTOM5rF0NyONVopq83Emuc94ACGFG0ySyVrOFc%3D&reserved=0>,
"rdfs": http://www.w3.org/2000/01/rdf-schema#<https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23&data=04%7C01%7CAparna.Garimella%40ihsmarkit.com%7Cf4a7cce01c1f4fd942aa08d9fba413c4%7Cc1156c2fa3bb4fc4ac073eab96da8d10%7C0%7C0%7C637817504392468912%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=ia%2BQ%2BLVomp3wT9S8dnSjEDe2f0xpW%2Bnn%2BNTU55odYbE%3D&reserved=0>,
"owl": http://www.w3.org/2002/07/owl#<https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.w3.org%2F2002%2F07%2Fowl%23&data=04%7C01%7CAparna.Garimella%40ihsmarkit.com%7Cf4a7cce01c1f4fd942aa08d9fba413c4%7Cc1156c2fa3bb4fc4ac073eab96da8d10%7C0%7C0%7C637817504392468912%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=Ig4MNt7f3DAJiSq4YfVt1oqUB8ellkKqPsJY3pOpwpY%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#<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#<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 Tuesday, 1 March 2022 17:04:31 UTC