Hello and a question about how to refer to operations

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 03:39:51 UTC