Re: [Specifications] Retracting operations (#246)

I think we may be talking a bit past each other because there is no agreed-upon, idiomatic way for a Hydra API to behave. Hydra makes data about possible HTTP operations available as `hydra:supportedOperation` described in `ApiDocument` and `hydra:operation` as inline hypermedia controls in the response to a previous request. Let's call these two mechanisms _static_ and _dynamic_.

The issue at hand is that the _static_ and _dynamic_ metadata may be conflicting. A `hydra:supportedOperation` may not be available in the current state of the resource. One suggested way to deal with this is to not treat `ApiDocumentation` as a static resource, but instead re-request every time it changes.

To treat out-of-bound metadata such as `ApiDocumentation` just as dynamic as the requested resource, however, is unintuitive. I don't think that's going to sit well with many developers. I think `ApiDocumentation` instead should be viewed almost as static as an `openapi.yml` file, to generate the initial skeleton of an API client.

Treating `ApiDocumentation` as a static resource then brings us back to the problem of being able to express that a `hydra:supportedOperation` is no longer available in the current state of the resource. Simply removing a `hydra:operation` from a response isn't enough; the client already knows the operation exists. The server thus must be able to tell the client that the cannot be successfully executed given the current state of the resource.

Another way to look at this is that `hydra:supportedOperation` does not specify operation availability on an instance of a resource, just on its interface or definition. This means that auto-generated clients cannot make `hydra:supportedOperation` available on resource instances; instead, the operations are infrastructure that is used only when the `hydra:operation` in a response indicates that the operation should be available.

Either way, the spec needs to clarify this somehow. I don't think we can close this without figuring out a different approach to fixing the problem.

-- 
GitHub Notification of comment by asbjornu
Please view or discuss this issue at https://github.com/HydraCG/Specifications/pull/246#issuecomment-1363956642 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Friday, 23 December 2022 13:32:53 UTC