I’ve been using JSON:API for a few years and am generally familiar with it. Likewise, I have been using OpenAPI/Swagger for a few years and am also familiar with it.
Up to this point I had not needed to implement the write-endpoints for updating relationships, so I only recently stumbled across what I believe is an incompatibility point between the two: OpenAPI, or at least most of the tooling for it, considers a request body on a DELETE request to be an error.
Specific to the JSON:API specs, this means designing a DELETE method on a relationship endpoint, e.g. DELETE /articles/1/relationships/comments from the specs, results in an error from most validation tools. For example, openapi-enforcer has:
Errors: [ EnforcerException: One or more errors exist in the OpenApi definition
at: paths
at: /teams/{teamId}/relationships/admins > delete
Property not allowed: requestBody ]
This topic is not to propose a change to JSON:API, instead, I am looking for guidance on how others have handled this difference between systems.
My current workaround does not strictly follow the JSON:API specs, but feels like it conforms to the heart of the specs that I’m okay with the nonconformity. (Especially because I have other validation/etc tooling, since using OpenAPI.)
Basically I add a path like DELETE /relationships/{name}/{id} so that (from the spec examples):
The only OpenAPI tool I’ve used has been Redoc for documentation, and I haven’t had any problems with this. That’s nothing like some of the other tools, apparently; I can describe a compliant JSON:API DELETE method for relationships without any complaints from the tool.
It’s worth noting that I’m not using any tools or frameworks for the implementation of my service or the clients.