CODEWITHSUNDEEP
httpresthttprequesthttp-method
shelley
shelley

Reputation: 7324

RESTful Alternatives to DELETE Request Body

While the HTTP 1.1 spec seems to allow message bodies on DELETE requests, it seems to indicate that servers should ignore it since there are no defined semantics for it.

4.3 Message Body

A server SHOULD read and forward a message-body on any request; if the request method does not include defined semantics for an entity-body, then the message-body SHOULD be ignored when handling the request.

I've already reviewed several related discussions on this topic on SO and beyond, such as:

Most discussions seem to concur that providing a message body on a DELETE may be allowed, but is generally not recommended.

Further, I've noticed a trend in various HTTP client libraries where more and more enhancements seem to be getting logged for these libraries to support request bodies on DELETE. Most libraries seem to oblige, although occasionally with a little bit of initial resistance.

My use case calls for the addition of some required metadata on a DELETE (e.g. the "reason" for deletion, along with some other metadata required for deletion). I've considered the following options, none of which seem completely appropriate and inline with HTTP specs and/or REST best practices:

My first preference would probably be to use the message body, second to custom HTTP headers; however, as indicated, there are some downsides to these approaches.

Are there any recommendations or best practices inline with REST/HTTP standards for including such required metadata on DELETE requests? Are there any other alternatives that I haven't considered?

Upvotes: 121

Views: 113330

Answers (5)

user3013432
user3013432

Reputation: 23

I would say that query parameters are part of the resource definition, thus you can use them to define the scope of your operation, then "apply" the operation. My conclusion is that Query Parameters as you defined it is the best approach.

Upvotes: 1

Nicholas Shanks
Nicholas Shanks

Reputation: 10971

What you seem to want is one of two things, neither of which are a pure DELETE:

  1. You have two operations, a PUT of the delete reason followed by a DELETE of the resource. Once deleted, the contents of the resource are no longer accessible to anyone. The 'reason' cannot contain a hyperlink to the deleted resource. Or,
  2. You are trying to alter a resource from state=active to state=deleted by using the DELETE method. Resources with state=deleted are ignored by your main API but might still be readable to an admin or someone with database access. This is permitted - DELETE doesn't have to erase the backing data for a resource, only to remove the resource exposed at that URI.

Any operation which requires a message body on a DELETE request can be broken down into at it's most general, a POST to do all the necessary tasks with the message body, and a DELETE. I see no reason to break the semantics of HTTP.

Upvotes: 12

shelley
shelley

Reputation: 7324

Despite some recommendations not to use the message body for DELETE requests, this approach may be appropriate in certain use cases. This is the approach we ended up using after evaluating the other options mentioned in the question/answers, and after collaborating with consumers of the service.

While the use of the message body is not ideal, none of the other options were perfectly fitting either. The request body DELETE allowed us to easily and clearly add semantics around additional data/metadata that was needed to accompany the DELETE operation.

I'd still be open to other thoughts and discussions, but wanted to close the loop on this question. I appreciate everyone's thoughts and discussions on this topic!

Upvotes: 61

Suresh Kumar
Suresh Kumar

Reputation: 11767

I suggest you include the required metadata as part of the URI hierarchy itself. An example (Naive):

If you need to delete entries based on a date range, instead of passing the start date and end date in body or as query parameters, structure the URI such a way that you pass the required information as part of the URI.

e.g.

DELETE /entries/range/01012012/31122012 -- Delete all entries between 01 January 2012 to 31st December 2012

Hope this helps.

Upvotes: -1

codeprogression
codeprogression

Reputation: 3441

Given the situation you have, I would take one of the following approaches:

  • Send a PUT or PATCH: I am deducing that the delete operation is virtual, by the nature of needing a delete reason. Therefore, I believe updating the record via a PUT/PATCH operation is a valid approach, even though it is not a DELETE operation per se.
  • Use the query parameters: The resource uri is not being changed. I actually think this is also a valid approach. The question you linked was talking about not allowing the delete if the query parameter was missing. In your case, I would just have a default reason if the reason is not specified in the query string. The resource will still be resource/:id. You can make it discoverable with Link headers on the resource for each reason (with a rel tag on each to identify the reason).
  • Use a separate endpoint per reason: Using a url like resource/:id/canceled. This does actually change the Request-URI and is definitely not RESTful. Again, link headers can make this discoverable.

Remember that REST is not law or dogma. Think of it more as guidance. So, when it makes sense to not follow the guidance for your problem domain, don't. Just make sure your API consumers are informed of the variance.

Upvotes: 12

Related Questions