DELETE 200 Clarification

1

From the Deleting resources of the JSON:api spec topic (emphasis mine):

200 OK
A server MUST return a 200 OK status code if a deletion request is successful and the server responds with only top-level meta data.

We are using a “soft delete” pattern, so this makes our DELETE implementation feel more like a PATCH, e.g., from the JSON:api PATCH spec:

200 OK
If a server accepts an update but also changes the resource(s) in ways other than those specified by the request (for example, updating the updated-at attribute or a computed sha ), it MUST return a 200 OK response. The response document MUST include a representation of the updated resource(s) as if a GET request was made to the request URL.

The DELETE spec reads, without an example, that the representation of the updated resource would not be returned. However, I’m thinking it should be, versus a single top-level meta object (as I read the spec, the only permitted response content is a top level meta object).

Thoughts on including the updated resource in the 200 OK for a DELETE where a soft delete is the implementation?

2

Personally, if using soft-delete where the resource is still visible in the API, I would just model that as a boolean deleted attribute that can be patched. That is what I am doing in all of my APIs. I reserve DELETE for “permanent” deletion where the resource is no longer available through the API (attempting to GET it would return 404). That seems to mesh well with JSON:API semantics (as you say, DELETE can’t return a resource representation.)

Note that the fact that it’s not available through the API does not mean it has to be physically deleted from the DB. That’s an implementation detail.

Note also that there’s still utility in being able to return a proper resource response from a DELETE request (e.g. a now modified parent resource of the deleted resource), though that is not part of the spec. Details in this issue.

1 Like
3

We are using a similar deleted boolean attribute. I argued for PATCH, but it started to bike-shed a bit. It happens. Thanks @cmeeren .