Why I Avoided Using a Body in a REST API DELETE Request

While implementing a gift API in Kakao Tech Campus, I had to decide where to put the value needed for a delete request. The feature itself was simple. It was an API for deleting a specific resource.

At first, I thought it would be fine to put the value in the body of a DELETE request. The server can read the body. But when I thought about the client side as well, it started to feel unclear. Clients, intermediate proxies, and documentation tools may not all handle DELETE bodies in the same way. An API is not finished just because the server code works. It is closer to a shared agreement with the client.

This post is a record of why I avoided using a body in a DELETE request and chose an API shape that makes the delete target easier to see.

First Approach

At first, I considered putting the value needed for deletion in the request body.

DELETE /api/wishlist
Content-Type: application/json

{
  "productId": 1
}

From the server side, this was possible. If I received the value as JSON, it also seemed easy to add more fields later. But from the API user's point of view, the body of a DELETE request may not be obvious at first glance.

Especially when the delete target is clearly one resource, it is easier to read if the target is shown in the URI rather than hidden in the body.

Query Parameter Check

The second option was using a query parameter.

DELETE /api/wishlist?productId=1

This was also usable. However, if the delete target is a resource identifier, I felt that a path variable fit better than a query parameter. A query parameter can look like a filter or option, so it felt a little unclear for expressing the target resource itself.

Approach

In the end, I chose to show the target resource in the URI path.

DELETE /api/wishlist/items/{productId}

With this shape, someone reading the request can immediately tell which resource is being deleted. The API documentation also becomes simpler, and the client side can understand how to use it more easily.

This does not mean that a DELETE body is absolutely impossible. In this project, the delete target was clear, so expressing it in the URI felt more appropriate than putting it in the body.

Checkpoints

The points I checked for the API design were:

• Is the delete target a resource identifier?
• Can someone understand the intention just by looking at the request?
• Is it easy for the client and documentation tools to handle?
• Will someone reading the API later understand what it means?

I tried not to choose an approach only because the server could handle it. An API is not just a server implementation detail. It is something the client also has to use.

Takeaway

This experience reminded me that in REST API design, whether the request works is not the only thing to check. The request shape should also be easy to read.

The main question was not whether a DELETE request can have a body. It was whether the API clearly shows which resource it deletes. So when the delete target was clear, I chose to express it with a path variable.