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.

As far as I understand the concept the API documentation is static, it contains resource type descriptions along their supported operations. The API responds with resource representations, which contain the resources which can have multiple types each of them multiple supported operations. For the actual resource not all of the operations are available, e.g. for the current user writing is not possible or the resource is in a state where update, deletion is not possible, etc. If the client calls an operation that is not available, that's an issue. One way to deal with the problem is describing only the available operations in the actual resource representation. Another way is describing all of them and telling that the actual operations is or is not available for the actual resource. I prefer the former one, e.g. in the case of a webpage it does not make sense to serve broken hyperlinks and write in the comment that you can try them out if you want to, but they are broken, so you are just wasting your time. Webpages just don't serve broken hyperlinks. Though maybe I misunderstood the problem and we are talking about something different here.

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


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

Received on Thursday, 5 January 2023 22:49:33 UTC