Re: Hello and a question about how to refer to operations

Hi Michael

Indeed this is an appropriate forum for such a question.
Unfortunately, I don't think there is a single answer for it.

The best, the most direct and safe way of referring an operation is
the resource's unique identifier. It is the '@id' you've mentioned,
which translates to the RDF's subject IRI of a statement. This way you
can query tripples for an operation of a given IRI and this will give
you a straight result.

I would use neither title nor description - these can be in various
languages and are in general for humans and I don't expect those to be
unique. You may find yourself stuck with some heavy fuzzy logic to
discover operations with that approach.

Another option would be to query it by it's predicates, i.e.
SELECT ?s ?p ?o WHERE { ?s hydra:method "GET" . ?s hydra:expects api:User . }
in SPARQL (sorry for any mistakes here - I haven't used it for a while).
This may give you unfortunately more results than one, depending on
the API, query, etc.

Finally, you can always introduce another way of uniquely identifying
a resource i.e. dcterms:identifier, but this may not be understood by
other clients as DCTerms is not mentioned in the specification.

I hope these answers will help you. Feel free to deliberate more.
Maybe some use cases would shed some more light on the topic.

Regards

Karol Szczepanski

pt., 6 sie 2021 o 05:40 Michael Glaesemann <grzm@seespotcode.net> napisał(a):
>
> Hello!
>
> There are a lot aspects of hydra that are very appealing to me. In particular, I like its open-world stance and its grounding in RDF triples via JSON-LD. Thank you for work on the Hydra specification.
>
> I have a question about how to refer to operations. I hope this is an appropriate forum for questions. If not, please feel free to direct me to a better place.
>
> I'd like to know how to refer to operations. Operations can have title and description properties, which can be useful when displaying options to users in a client interface. I'm looking for a way to refer to operations by some unique identifier so we can refer to operations unambiguously.
>
> My use case is a little different from the gui-oriented examples I've seen in Hydra applications. I'm looking at generating client api libraries for programming languages.  (Think clients generated from OpenAPI specs to get the general idea, but data-oriented rather than function-oriented.) Ideally the identifier would be some unique, human-understandable label. I know this use case is a little different, and programming api libraries can be less dynamic than a user-driven client, which might not be Hydra's wheelhouse, but the other aspects of api documentation are compelling enough for me that I'd like to see if I can make it work.
>
>
> A few options I've thought about:
>
> * Use the title. It's a string can be used to identify the operation to the user. It's shorter than the description, which makes it more appealing from a programming api perspective. That said, the examples for titles are phrases, which aren't as useful, and there's no explicit uniqueness aspect to title properties (AFAICT) and title itself doesn't necessarily encourage terseness or uniqueness. Using Example 11 from the spec, the title of the first supportedOperation is "Creates a new comment". I'm looking for something like "CreateComment". For comparison OpenApi has an optional OperationId property that could be used for this.
>
> * Add an @id property that uniquely identifies the operation, perhaps as an IRI with a fragment, and use the fragment as the operation name for the purposes of the operation name in the client application. This is similar to the usage of @id in https://github.com/HydraCG/Specifications/issues/156 "Operation linked to class and property" (modified to make the supportedOperation value an array, rather than an object):
>
>
>        "supportedOperation": [{
>           "@id": "http://example.org/dataset-1#slice-get",
>           "@type": "Operation",
>           "method": "GET",
>           "expects": "http://example.org/dataset-1#slice-input",
>           "returns": "http://purl.org/linked-data/cube#Slice"
>         }]
>
>
> Another example of this is in https://github.com/HydraCG/Specifications/issues/241 "Retracting operations"
>
>
> GET /api?documentation
>
> {
>   "supportedClass": "api:User",
>   "api:User": {
>     "supportedOperation": {
>       "@id": "api:deleteUser",
>       "method": "DELETE"
>     }
>   }
> }
>
>
> * Leverage multiple type assignment and use a schema.org Action property, such as name to uniquely identify the operation. I'm thinking of something like (extending an example from https://github.com/HydraCG/Specifications/issues/149 "hydra:search with HTTP POST")
>
>
> {
>     "@id": "http://api.example.com/issues",
>     "operation": [ {
>         "@type": [ "Operation", "schema:SearchAction" ],
>         "method": "POST",
>         "schema:name" "IssueSearch"
>     }, {
>         "@type": [ "Operation", "schema:CreateAction" ],
>         "method": "POST",
>         "expects": "foo:Issue",
>         "schema:name": "CreateIssue"
>     } ]
> }
>
>
> Another thought I've had is subclassing hydra:Operation for each unique operation. That doesn't seem quite right, however, as individual operations are instances, while classes define domains of instances. That said,  https://github.com/HydraCG/Specifications/issues/160 "Expressing actions (#154) within ApiDocumentation" shows an example similar to this:
>
>
> {
>   "supportedClass": {
>     "@id": "ex:Car",
>     "supportedProperty": {
>       "@id": "ex:steeringWheel",
>       "supportedOperation": [ {
>         "@type": "ex:TurnLeftOperation"
>       }, {
>         "@type": "ex:TurnRightOperation"
>       } ]
>     }
>   }
> }
>
>
> I've read through the spec fairly closely. I've also skimmed through the mailing list archives, and looked through the open and closed issues on the spec GitHub repo (https://github.com/HydraCG/Specifications) looking for discussion around operations. I haven't seen much that relates directly to this question, but I'm still very new to Hydra. I'm not sure I'm even framing a question that's sensible from Hydra's perspectives and goals.
>
> Any clarification or recommendations, or pointers to additional resources would be appreciated.
>
> Best,
>
> Michael Glaesemann
> grzm seespotcode net
>
>
>
>
>

Received on Friday, 6 August 2021 18:45:58 UTC