Is an entity body allowed for an HTTP DELETE request?

Question

When issuing an HTTP DELETE request, the request URI should completely identify the resource to delete. However, is it allowable to add extra meta-data as part of the entity body of the request?

Hyperostosis

In ASP.NET WebApi 2 FromBody Parameters are ignored for HttpDelete endppoints. – Figurative

I have a similar concern, but my case is different. I want to issue a batch delete request when I want to delete hundred objects. Certainly it is a great performance boost for pre HTTP 2.0 networks. – Uvarovite

Have there been any changes in HTTP/2 ? – Dreamy

Answer 1

The spec does not explicitly forbid or discourage it, so I would tend to say it is allowed.

Microsoft sees it the same way (I can hear murmuring in the audience), they state in the MSDN article about the DELETE Method of ADO.NET Data Services Framework:

If a DELETE request includes an entity body, the body is ignored [...]

Additionally here is what RFC2616 (HTTP 1.1) has to say in regard to requests:

• an entity-body is only present when a message-body is present (section 7.2)
• the presence of a message-body is signaled by the inclusion of a Content-Length or Transfer-Encoding header (section 4.3)
• a message-body must not be included when the specification of the request method does not allow sending an entity-body (section 4.3)
• an entity-body is explicitly forbidden in TRACE requests only, all other request types are unrestricted (section 9, and 9.8 specifically)

For responses, this has been defined:

• whether a message-body is included depends on both request method and response status (section 4.3)
• a message-body is explicitly forbidden in responses to HEAD requests (section 9, and 9.4 specifically)
• a message-body is explicitly forbidden in 1xx (informational), 204 (no content), and 304 (not modified) responses (section 4.3)
• all other responses include a message-body, though it may be of zero length (section 4.3)

Update

And in RFC 9110 (June 2022), The fact that request bodies on GET, HEAD, and DELETE are not interoperable has been clarified.

section 9.3.5 Delete

Although request message framing is independent of the method used, content received in a DELETE request has no generally defined semantics, cannot alter the meaning or target of the request, and might lead some implementations to reject the request and close the connection because of its potential as a request smuggling attack (Section 11.2 of [HTTP/1.1]). A client SHOULD NOT generate content in a DELETE request unless it is made directly to an origin server that has previously indicated, in or out of band, that such a request has a purpose and will be adequately supported. An origin server SHOULD NOT rely on private agreements to receive content, since participants in HTTP communication are often unaware of intermediaries along the request chain.

Polemist

@Jason Definitely. You could also use custom headers to pass additional data, but why not use the request body. – Polemist

Although the spec does not forbid DELETE requests from having a message-body, section 4.3 seems to indicate that the body should be ignored by servers since there are no "defined semantics" for DELETE entity-bodies: "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." – Skepful

Please note that a lot of clients are also unable to send a DELETE with a body. This just burned me on Android. – Sciatica

@KarmicCoder: Great point. More info: Sending HTTP DELETE request in Android. – Fishbolt

Lots of discussion about implementation mixed with HTTP spec. Clients will implement things in the way they interpret the spec, do not confuse this with the meaning of the spec. The fact is that the spec leaves this ambiguous. I disagree with interpretation that because there is no defined semantic for entity-body that there is an implication that it should be ignored. I think people are working backwards from clients specific interpretations that exist (Jersey, Android test clients, etc.) and trying to justify the interpretation rather than attempting to be true to spec. Humans are fallible. – Zacharia

@Zacharia I thought I worked my way through the spec, and not only to justify a particular implementation's behavior. But as you say, it's ambiguous, and if one implements a server or a client, a decision has to be made at some point. – Polemist

@Polemist the language is a bit ambiguous, but the intent is not. I asked the authors and shelley (in this thread) is correct. The next version of the HTTP specification will be more precise. – Worldling

Answer 2

The 2014 update to the HTTP 1.1 specification (RFC 7231) explicitly permits an entity-body in a DELETE request:

A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.

Benthamism

the latest un-approved version of the spec removes this requirement. The latest approved version is still the RFC2616 quoted above. – Compony

Which version? Version 20 still has the same wording as version 19 I linked above: "Bodies on DELETE requests have no defined semantics. Note that sending a body on a DELETE request might cause some existing implementations to reject the request." – Benthamism

Version 26 suggestions that you can permit a body: A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request. So it comes with a backward compatibility warning, it is suggesting that the next standard will be saying: 'yep! DELETE can have a body`. – Amil

I'd say the only correct interpretation of the spec for any client implementation of HTTP is to assume that DELETE and GET may have a body and that servers that accept/require those conform to the the HTTP spec. Based on this, any client implementation that does not support this is effectively not compatible with HTTP because it does not support all servers out there that interpret the spec in a perfectly valid way. Actually disallowing this in the spec would be a compatibility breaking change. The note about semantics could be applied to POST as well: out of the scope of the spec. – Inquiline

It doesn't matter if the client doesn't support bodies on DELETE requests. If it never sends them, it doesn't have to worry about what the server would do with them. – Faunia

RFC 7231 section 4.3.5 finalizes the language from version 26 with A payload within a DELETE request message has no defined semantics. So the body is allowed. – Persian

Body is allowed but should not be relevant to the request. There's absolutely no point in using it. – Worldling

@Worldling I disagree - I want to implement a "safe" DELETE method in my REST API that requires some additional parameter that must be set so that merely visiting the URL can't do any damage. It seems to me like placing that in the body would be ideal. – Sycophancy

@Sycophancy While the spec doesn't necessarily forbid a payload, such a feature might only be usable by your own client. Your client will further only be able to use that feature against your API, which is therefore somehow tightly coupled to your API as well. This is exactly what REST tries to avoid. If you don't want a resource from being deleted by an unauthorized client use authentication mechanisms to prevent such things. If you really need to send complicated parameters to the server to decide whether to delete the resource or not use POST though I'd question the desing to start with – Pi

@Worldling I disagree as well. A body in the DELETE request is useful if for example you want to instruct a server to remove multiple entities at once, with the ID's provided to the request via a payload in the body (passing these via URL query params might be too large) – Toshiatoshiko

@AdamReis, I'm not saying it's not useful. I'm only arguing that this is a bad idea given the HTTP specification and the fact that many conforming clients/servers potentially ignore it. – Worldling

Anyway, I brought this up to the group that develops the HTTP spec, and the language is being adjusted for the next version. This is what it's saying right now: A client SHOULD NOT generate a body in a DELETE request. A payload received in a DELETE request has no defined semantics, cannot alter the meaning or target of the request, and might lead some implementations to reject the request. – Worldling

@Worldling well your comment above said "There's absolutely no point in using it", which to me relates to the usefulness of it. But I agree, while it would be useful, unfortunately it seems it's currently not usable with the current specs of HTTP, so best to switch to a POST or PUT request for those cases, even if they are semantically incorrect. – Toshiatoshiko

Sure, that makes sense – Worldling

Answer 3

Some versions of Tomcat and Jetty seem to ignore a entity body if it is present. Which can be a nuisance if you intended to receive it.

Amniocentesis

Google App Engine instantiates and passes an empty default entity instead of the request body. – Musso

Further info about Tomcat: How to make Apache Tomcat accept DELETE method. – Fishbolt

Answer 4

One reason to use the body in a delete request is for optimistic concurrency control.

You read version 1 of a record.

GET /some-resource/1
200 OK { id:1, status:"unimportant", version:1 }

Your colleague reads version 1 of the record.

GET /some-resource/1
200 OK { id:1, status:"unimportant", version:1 }

Your colleague changes the record and updates the database, which updates the version to 2:

PUT /some-resource/1 { id:1, status:"important", version:1 }
200 OK { id:1, status:"important", version:2 }

You try to delete the record:

DELETE /some-resource/1 { id:1, version:1 }
409 Conflict

You should get an optimistic lock exception. Re-read the record, see that it's important, and maybe not delete it.

Another reason to use it is to delete multiple records at a time (for example, a grid with row-selection check-boxes).

DELETE /messages
[{id:1, version:2},
{id:99, version:3}]
204 No Content

Notice that each message has its own version. Maybe you can specify multiple versions using multiple headers, but by George, this is simpler and much more convenient.

This works in Tomcat (7.0.52) and Spring MVC (4.05), possibly w earlier versions too:

@RestController
public class TestController {

    @RequestMapping(value="/echo-delete", method = RequestMethod.DELETE)
    SomeBean echoDelete(@RequestBody SomeBean someBean) {
        return someBean;
    }
}

Fluoro

Having bodies in GET (and DELETE) is clearly mistreating HTTP and REST. There are other mechanisms for dealing with concurrency control (e.g. If-Modified-Since and etags). – Forficate

How is it CLEARLY mistreating it when the spec does not forbid the body in DELETE? – Fluoro

Because you're not meant to do anything with the body. See: https://mcmap.net/q/40417/-http-get-with-request-body – Forficate

that's about GET. this is about DELETE – Fluoro

This is exactly the same issue: GET allows you to retrieve the representation of the resource identified by the URI, and DELETE deletes the resource identified by the URI. Use a different URI for other versions if you want to delete specific versions. The URI should be the sole identifier of the resource in HTTP/REST. Use metadata in headers if you need do handle concurrency (e.g. If-Unmodified-Since or Etag, that's what they're for). – Forficate

@Forficate you think a resource should get a new URL every time it's changed? – Fluoro

Sorry hard to remember this discussion almost a year later. No, not necessarily (the main issue here was suggesting to use a body in DELETE). URIs are identifiers, it's up to you to choose what they identify, more importantly, what you mean. For example, this answer has a URI (in fact multiple of them depending on who shares it), yet each revision has its own URI too 1 and 2. It all depends on what you mean to identify with the identifier. – Forficate

I would use the header to pass the version, not the body. – Poinsettia

@Poinsettia how would you delete multiple records at once with OCC? – Fluoro

For me it's also very interesting that body parameters do not show on server/proxy logs, it's an added layer of security, I hate when the server log displays something like http://server/put?iduser=3434&stuff=mystuff ... rather than http://server/put – Buettner

Use ETag header instead of a version field in a body – Cochineal

@malcolmhall it's cool to be idealistic but that isn't going to work well with lots of selected records to delete, especially if using "all fields" OCC. It would also be pretty irritating to split and combine the records into headers and body depending on the method. – Fluoro

Doing a POST when you really wanted a DELETE with some metadata is a perfectly good work around when your framework is overzealous in interpreting the spec for you. For good measure you can squeeze in the verb in the url as well and you are well on your way to implementing RPC over http. I see no good technical reason whatsoever to disallow request bodies on GET/DELETE. Consider e.g. sending a complex query to server is that a GET or a POST? I vote for GET. What about delete by query? Squeezing this into the headers or url is silly and flaky. – Inquiline

Using DELETE with a semantic request body explicitly means that you are leaving HTTP behind and you are defining your own variation. Whether you prefer using GET or DELETE with request bodies is kind of irrelevant. Conforming HTTP tools will drop or ignore bodies. – Worldling

If you're deleting multiple resources in one request, you are already diverging from the meaning of the verb in the HTTP spec, which is "The DELETE method requests that the origin server remove the association between the target resource and its current functionality". The "target resource" of DELETE /messages is /messages, implying that the entire collection would be deleted. If you wanted to stay RESTful, a more appropriate mechanism might be to use PATCH /messages, treating the collection as a single resource, and the deletions as changes to that resource. – Deduction

One reason I can think of using body (and the reason that brought me this post), would be to give more information about what to do with a deleted record and its children. In my application, when deleting, I want to give the ability for the user to select a new place for the children of the deleted item to live under, and the body request body would be a great place to pass this information. I could put it in the request path, but I want the path to always just be the path of the resource being deleted. – Mylonite

Rather use headers or query parameters for that. – Piccard

Answer 5

Just a heads up, if you supply a body in your DELETE request and are using a google cloud HTTPS load balancer, it will reject your request with a 400 error. I was banging my head against a wall and came to found out that Google, for whatever reason, thinks a DELETE request with a body is a malformed request.

Laplace

for whatever reason - because the spec says so :P – Luhe

The spec doesn't "say so" it just says that the body isn't specifically defined. If it's not defined, and you want to ignore it, cool...go ahead and ignore it. But rejecting the request outright seems extreme and unnecessary. – Laplace

Don't rely on undefined behavior. It's a pretty common best practice. – Worldling

@Worldling there's explicitly undefined behaviour (such as you see describe in the specifications of the C language for example) and there's behaviour that is permitted but simply not described. Using a message body in DELETE is the latter. – Sycophancy

Seems google have now allowed body with DELETE, here : cloud.google.com/load-balancing/docs/… – Atonement

Answer 6

Roy Fielding on the HTTP mailing list clarifies that on the http mailing list https://lists.w3.org/Archives/Public/ietf-http-wg/2020JanMar/0123.html and says:

GET/DELETE body are absolutely forbidden to have any impact whatsoever on the processing or interpretation of the request

This means that the body must not modify the behavior of the server. Then he adds:

aside from the necessity to read and discard the bytes received in order to maintain the message framing.

And finally the reason for not forbidding the body:

The only reason we didn't forbid sending a body is because that would lead to lazy implementations assuming no body would be sent.

So while clients can send the payload body, servers should drop it and APIs should not define a semantic for the payload body on those requests.

Battlement

Answer 7

It appears to me that RFC 2616 does not specify this.

From section 4.3:

The presence of a message-body in a request is signaled by the inclusion of a Content-Length or Transfer-Encoding header field in the request's message-headers. A message-body MUST NOT be included in a request if the specification of the request method (section 5.1.1) does not allow sending an entity-body in requests. 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.

And section 9.7:

The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.c

So it's not explicitly allowed or disallowed, and there's a chance that a proxy along the way might remove the message body (although it SHOULD read and forward it).

Lepto

Answer 8

tl;dr: Techically a DELETE request with a request body is allowed, but it's never useful to do so.

---

I don't think a good answer to this has been posted, although there's been lots of great comments on existing answers. I'll lift the gist of those comments into a new answer:

This paragraph from RFC7231 has been quoted a few times, which does sum it up.

A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.

What I missed from the other answers was the implication. Yes it is allowed to include a body on DELETE requests, but it's semantically meaningless. What this really means is that issuing a DELETE request with a request body is semantically equivalent to not including a request body.

Including a request body should not have any effect on the request, so there is never a point in including it.

Worldling

"semantically meaningless" doesn't mean the same as "has no defined semantics". The former means that it cannot have any meaning. The latter simply means that the RFC itself does not specify what those semantics might be. (I write RFCs) – Sycophancy

In other words, if the implementor of an API desires to define some semantics for themselves, they're perfectly free to do so. – Sycophancy

@Sycophancy this is definitely a mis-interpretation. By that definition any HTTP request body has no defined semantics, but DELETE and GET are specifically called out in the specification. Here's a snippet from a yet-to-be-published draft talking about this specifically about the GET request: – Worldling

" Finally, note that while HTTP allows GET requests to have a body syntactically, this is done only to allow parsers to be generic; as per [RFC7231], Section 4.3.1, a body on a GET has no meaning, and will be either ignored or rejected by generic HTTP software." – Worldling

I don't disagree with you that this is unclear in the currently released RFC's, but if you don't believe me, I would invite you to ask the authors after their intent for DELETE and GET. You'll find that it lines up with my answer. Like you, I am also involved in standards bodies and I'm not just a lone person with an opinion about how the RFC should be interpreted. – Worldling

If that's the case then 7231 is poorly worded, and should have said "the payload body MUST be ignored". Which draft are you referring to above? – Sycophancy

@Sycophancy my source tools.ietf.org/html/draft-ietf-httpbis-bcp56bis-06 I 100% agree with you and I think the current wording is also responsible for people adding request bodies to GET. The HTTP WG is working on a new version of th HTTP specification so maybe it's a good time to clean that language up a bit. – Worldling

I expect @mnot will be at IETF next month - I'll tease him about it then – Sycophancy

I brought this up at the httpwg, I am not sure if this is conclusive but here it is: github.com/httpwg/http-core/issues/202 – Worldling

Answer 9

Using DELETE with a Body is risky... I prefer this approach for List Operations over REST:

Regular Operations

GET /objects/ Gets all Objects

GET /object/ID Gets an Object with specified ID

POST /objects Adds a new Object

PUT /object/ID Adds an Object with specified ID, Updates an Object

DELETE /object/ID Deletes the object with specified ID

All Custom actions are POST

POST /objects/addList Adds a List or Array of Objects included in body

POST /objects/deleteList Deletes a List of Objects included in body

POST /objects/customQuery Creates a List based on custom query in body

If a client doesn't support your extended operations they can work in the regular way.

Westing

Using a POST is not a good RESTy way to create new resources because the semantics of POST responses are unclear, especially in the context of Location headers. You are essentially leaving HTTP behind and stack RPC on top. The proper "HTTP/REST way" is to create resources using PUT w/ the If-None-Match: * header (or spec'ing proper HTTP methods, see MKCOL etc). – Funerary

I use POST to crete objects, PUT to update them and PATCH to make partial updates.POST /objects/deleteList doesnt make any sense for me, the "rest way" should be call DELETE /objects/{object_id} or DELETE /objects?objectNameLike={object_prefix} for example. – Seeress

@Funerary creating a new resource with PUT breaks the idempotent rule since you don't know the ID of the resource beforehand. – Raising

@Seeress settings the list of ids in the query string may work until you pass too many and exceed the url length limit, then you must move to a POST request. That's the main reason I know people want to have a body on DELETE. – Raising

@Raising If you are sending too many ids in a request, so many you may exceed the url lenght limit you are doing something very wrong in the first place. Sometimes people want things to circumvent their problems the easy way instead of addressing the problem itself. – Seeress

The RFC'ed standard way to create new HTTP resources is using PUT in combination with If-None-Match: * (similar w/ MKCOL and such). There is no idempotency issue. – Funerary

@Funerary so the same request executed twice produce different result (two different resources are created) and yet you claim it is idempotent ? This is logically false. Check this instead https://mcmap.net/q/54190/-should-http-put-create-a-resource-if-it-does-not-exist – Raising

@Seeress every technical solution answers a business issue. You cannot invalidate a business issue. Typically a back office will offer the possibility to select a large number of entities and apply batch actions to them. Taking a 16 chars entity id and a 2048 url max length, that's only 128 object selected, which is not that much for a back office. That being said, what do you propose to circumvent the technical problem ? – Raising

@Raising Did you read up on what If-None-Match does? It does not create two different resources. What you describe is the behavior of POST based APIs (those create multiple resources, because they are not idempotent like a proper PUT). (all those issues have been dealt with in CalDAV/CardDAV APIs, which do - and spec - that properly) – Funerary

@Funerary I know what If-None-Match does. To use PUT in an idempotent way you must provide the ID, which is fine for an update but is not for most creation scenarios. So you can hardly have an idempotent PUT for creating resources. – Raising

Answer 10

It is worth noting that the OpenAPI specification for version 3.0 dropped support for DELETE methods with a body:

see here and here for references

This may affect your implementation, documentation, or use of these APIs in the future.

Parlor

Notably they added back in after some discussion. See here for reference. – Mean

Answer 11

It seems ElasticSearch uses this: https://www.elastic.co/guide/en/elasticsearch/reference/5.x/search-request-scroll.html#_clear_scroll_api

Which means Netty support this.

Like mentionned in comments it may not be the case anymore

Boutique

If you use apache http client you can easily create your own versions of GET and DELETE by extending HttpEntityEnclosingRequestBase and making the getMethod() method return GET or DELETE. We use this for talking to elasticsearch. – Inquiline

dead link - great. we need more of those link answers - not – Muscolo

The linked documentation now contains only POST requests, no DELETEs. Might be worth adding a note to this answer? – Obstetrician

Elasticsearch uses body with GET requests too. – Ireneirenic

Answer 12

Several other answers mention RFC 7231 which had effectively said that a DELETE request is allowed to have a body but it is not recommended.

In 2022, RFC 7231 was superseded by RFC 9110: HTTP Semantics, which now says:

[...] content received in a DELETE request has no generally defined semantics, cannot alter the meaning or target of the request, and might lead some implementations to reject the request and close the connection [...]. A client SHOULD NOT generate content in a DELETE request unless it is made directly to an origin server that has previously indicated, in or out of band, that such a request has a purpose and will be adequately supported. An origin server SHOULD NOT rely on private agreements to receive content, since participants in HTTP communication are often unaware of intermediaries along the request chain.

This language has been strengthened from the previous language, to say that even though it is allowed, you really need to be very careful when using it because (for example) some users might be behind a proxy that would strip the body from the request in order to combat "request smuggling".

Urumchi

Answer 13

In case anyone is running into this issue testing, No, it is not universally supported.

I am currently testing with Sahi Pro and it is very apparent a http DELETE call strips any provided body data (a large list of IDs to delete in bulk, as per endpoint design).

I have been in contact with them several times, also sent three separate packages of scripts, images and logs for them to review and they still have not confirmed this. A failed patch, and a missed conference calls by their support later and I still haven't gotten a solid answer.

I am certain Sahi does not support this, and I would imagine many other tools follow suite.

Hadleigh

It is implemented in the latest version of Sahi Pro. Since Sahi uses java to make HTTP calls, and Java had a bug prior to version 1.8 which won't let user make a DELETE request. So with Java 1.8 onwards and Sahi Pro 6.1.1(to be public soon), people can make DELETE request with body in Sahi. – Yanyanaton

Answer 14

This is not defined.

A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.
https://www.rfc-editor.org/rfc/rfc7231#page-29

Pastiness

Specifically, RFC 7231 section 4.3.5 – Persian

This exact quote was already included in previous answers, this answer should be deleted. – Pirandello

Answer 15

Practical answer: NO

Some clients and servers ignore or even delete the body in DELETE request. In some rare cases they fail and return an error.

Steam

Answer 16

As other answers have noted, using a request body with a DELETE request is ... questionable ... at best.

RFC 9110 does say:

A client SHOULD NOT generate content in a DELETE request unless it is made directly to an origin server that has previously indicated, in or out of band, that such a request has a purpose and will be adequately supported.

I want to point out at least 1 implementation in the wild where a request body on a DELETE is actually required:

Spotify's REST API for removing playlist tracks
https://developer.spotify.com/documentation/web-api/reference/remove-tracks-playlist

It is an HTTP DELETE request, where the body is a JSON document specifying the tracks to remove and the snapshot to remove them from.

Vaenfila

Answer 17

Might be the below GitHUb url will help you, to get the answer. Actually, Application Server like Tomcat, Weblogic denying the HTTP.DELETE call with request payload. So keeping these all things in mind, I have added example in github,please have a look into that

https://github.com/ashish720/spring-examples

Bullhead