# Request for guidance on OpenAPI disallowing DELETE with request body

**URL:** <https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345>\
**Category:** Uncategorized\
**Created:** [November 22, 2021, 10:01pm UTC](https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345 "2021-11-22T22:01:14Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![saibotsivad](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/saibotsivad/32/778_2.png) [@saibotsivad](https://discuss.jsonapi.org/u/saibotsivad)\
**Post date:** [November 22, 2021, 10:01pm UTC](https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345/1 "2021-11-22T22:01:14Z")

</div>

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](https://jsonapi.org/format/#crud-updating-to-many-relationships), results in an error from most validation tools. For example, [openapi-enforcer](https://byu-oit.github.io/openapi-enforcer/) has:

```auto
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.

---

<div class="post-metadata">

**Author:** ![saibotsivad](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/saibotsivad/32/778_2.png) [@saibotsivad](https://discuss.jsonapi.org/u/saibotsivad)\
**Post date:** [November 22, 2021, 10:08pm UTC](https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345/2 "2021-11-22T22:08:38Z")

</div>

I’ll start 😅

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):

```http
DELETE /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "comments", "id": "12" },
    { "type": "comments", "id": "13" }
  ]
}

```

would become _two_ requests:

```http
DELETE /articles/1/relationships/comments/12 HTTP/1.1
DELETE /articles/1/relationships/comments/13 HTTP/1.1

```

Of course this has some pros and cons:

- Pro: it is supported by OpenAPI specs, so I can use that tooling.
- Pro: no more complaints from other tooling for request bodies on DELETEs.
- Pro: requests are idempotent (compared to using PATCH instead of DELETE).
- Con: no longer valid JSON:API, may throw errors in other tooling or require additional customization?
- Con: cannot delete multiple relationships at once.
- Con: if you have multiple types on a single relationship name, there’s potential ambiguity.

For my current system architecture this design works well, but I would love to hear if anyone else has come up with other ideas!

---

<div class="post-metadata">

**Author:** ![fdrake](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/fdrake/32/654_2.png) [@fdrake](https://discuss.jsonapi.org/u/fdrake)\
**Post date:** [November 24, 2021, 12:28am UTC](https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345/3 "2021-11-24T00:28:44Z")

</div>

The only OpenAPI tool I’ve used has been [Redoc](https://github.com/Redocly/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.

-Fred

---

<div class="post-metadata">

**Author:** ![Bernhard](https://avatars.discourse-cdn.com/v4/letter/b/c37758/32.png) [@Bernhard](https://discuss.jsonapi.org/u/Bernhard)\
**Post date:** [November 24, 2021, 4:29pm UTC](https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345/4 "2021-11-24T16:29:39Z")

</div>

If I understand the following correctly, the newest versions of OpenAPI spec do allow for it. Maybe tooling just needs to catch up with this…

> <https://github.com/OAI/OpenAPI-Specification/issues/1801>
>
> I would like the specification to allow a requestBody in the DELETE method and o…ther methods without explicitly defined semantics.
> 
> One of the answers in this \[StackOverflow \](https://stackoverflow.com/questions/299628/is-an-entity-body-allowed-for-an-http-delete-request) post states: "The spec does not explicitly forbid or discourage it, so I would tend to say it is allowed."
> I would agree with that statement.
> 
> Currently the OpenAPI spec says "The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies."
> 
> I think this should raise a notice, but not be unsupported and raise an error.
> 
> Addendum:
> 
> As I mentioned in a comment below, if you do choose to create a batch delete method on your API, whether or not anyone recommends it, make sure to check your cache settings and think about how these settings will interact with DELETE requests. Calling \`DELETE\` on \`/users\` with data \`\[3,4\]\` will not invalidate the cache for \`/users/3\` or \`/users/4\`, so a GET request to either of them may return invalid data depending on cache settings. My comment below describes methods of mitigating this.

> <https://github.com/OAI/OpenAPI-Specification/pull/2117>
>
> Fixes #1801 per TSC discussion of 2019-05-30 which requested a PR for review.
> 
> …
> refactored against v3.1.0 per @webron https://github.com/OAI/OpenAPI-Specification/pull/1937#issuecomment-577720158

---

<div class="post-metadata">

**Author:** ![saibotsivad](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/saibotsivad/32/778_2.png) [@saibotsivad](https://discuss.jsonapi.org/u/saibotsivad)\
**Post date:** [November 24, 2021, 5:01pm UTC](https://discuss.jsonapi.org/t/request-for-guidance-on-openapi-disallowing-delete-with-request-body/2345/5 "2021-11-24T17:01:03Z")

</div>

Oh yeah, I see that now in the 3.1.0 specs, thanks!

I guess the thing to do now is to contribute to the tooling ecosystem to help get it 3.1.0 compatible. 🎉