I have an API that makes frequent use of links for many kinds of operations (e.g. confirm an order). When these links are not available, that means the operation is not allowed.
However, I see no parallel to “link missing = operation unavailable” when it comes to PATCH and DELETE. According to the JSON-API spec, these requests are sent to the resource’s self link. But the self link in general allows GET, PATCH and DELETE, so I can’t remove the link if e.g. deletion is not allowed.
A way that seems consistent with other link operations and with hypermedia is to add separate links called patch and delete that are identical to the self link, but which can be removed from the response when the respective operations are not allowed. However, this seems to run counter to the JSON-API spec, which says that GET and PATCH should be sent to the self link.
What I am currently doing is simply having property attributes called something like canDelete and canPatch. But then I am special-casing these two operations among all my other links. This would also be the case if adding e.g. a meta.verbs list to the self link. So it feels like no more than the lesser of the two evils, so to speak.
How are other people communicating whether PATCH and DELETE is allowed?
I often use the first option you mentioned, however, model it to our data, e.g. canConfirm, so it feels less ugly and more in a way you would talk to end-users.
Another one I use is letting other attributes explain a status, e.g status: "invoiced" means you won’t be able to use DELETE, and the docs should then explain that you can’t delete an already invoiced order.
Both assume the client knows the nature of the data of the server and it can’t be used as a generic client which can consume any data. As far as I known that is not the aim of JSON:API either.
When an order has become immutable, why not just return an error with a proper ‘about’ and/or ‘detail’ and http status (405 method not allowed) on PATCH and DELETE? https://jsonapi.org/format/#error-objects
That requires the client to actually try the PATCH/DELETE request. UI/UX concerns may require this to be indicated in the UI beforehand (e.g. to disable controls as soon as the entity becomes read-only).
and keeping a state/process indicator in you attributes? Probably something you track on the server side already.
But Patch and Delete links are probably more explicit, elegant then.
What if a non UI client follows a self link in this case?
That can work, though it’s a bit higher friction since the client must parse headers, and more importantly, you won’t get the information if you get the resource as an included resource. You must GET the self link to obtain the necessary information.
Also it might be mixing the domain protocol (resource definitions and semantics, i.e. “this order may not be edited”) with the HTTP protocol (“this URI supports these verbs”). Whether you care about that is up to you and your API.
Yes, parsing headers seems not always straight forward, javascript/CORS and using headers isn’t fine grained enough for many use cases with included recourses.
Although, I think that an edit button on an order or article (in a included resource) should open an editor and do a GET self to have fresh data and have an ‘explicit situation’ for editing/deleting that one document (maybe lock something somewhere in the backend). In that case using headers would work.
Regarding mixing protocols, isn’t adding specific DELETE or PATCH links, or even allowances in metadata, simmilar?
Although, I think that an edit button on an order or article (in a included resource) should open an editor and do a GET self to have fresh data and have an ‘explicit situation’ for editing/deleting that one document (maybe lock something somewhere in the backend).
Now you’re making quite a few UI/UX assumptions. I’m working on systems where this works differently.
Regarding mixing protocols, isn’t adding specific DELETE or PATCH links, or even allowances in metadata, simmilar?
Maybe, maybe not. For this topic, I’d say it’s up to you to decide how idealistic you want to be.