I'm designing a RESTful API, and want to ensure proper adherence to HTTP idempotency rules for PUT and DELETE methods. I understand that idempotency means repeated requests should have the same server-side effect as a single request, but I'm unclear on specific implementation details:

1. For PUT: If a client sends the same PUT payload multiple times, should the server overwrite the resource every time, or skip the write operation if the data is unchanged?

   If the server skips redundant writes, how does it detect whether the data is identical (e.g., comparing hashes, field-by-field checks, or using ETag/If-Match headers)?

2. For DELETE: If a client sends a DELETE request for a resource that no longer exists, should the server return:

   • 404 Not Found (to indicate the resource is already gone)?

   • 204 No Content (to treat it as a success, since the desired state is achieved)?

I'm designing a RESTful API, and want to ensure proper adherence to HTTP idempotency rules for PUT and DELETE methods. I understand that idempotency means repeated requests should have the same server-side effect as a single request, but I'm unclear on specific implementation details:

1. For PUT: If a client sends the same PUT payload multiple times, should the server overwrite the resource every time, or skip the write operation if the data is unchanged?

   If the server skips redundant writes, how does it detect whether the data is identical (e.g., comparing hashes, field-by-field checks, or using ETag/If-Match headers)?

2. For DELETE: If a client sends a DELETE request for a resource that no longer exists, should the server return:

   • 404 Not Found (to indicate the resource is already gone)?

   • 204 No Content (to treat it as a success, since the desired state is achieved)?

• rest
• http
• http-delete
• idempotent
• http-put

Share Improve this question Follow edited Mar 13 at 15:45 Mureinik 313k5454 gold badges363363 silver badges392392 bronze badges asked Mar 13 at 12:47 yinebebtyinebebt 1311 silver badge44 bronze badges

Add a comment  | 

2 Answers 2

Sorted by: Reset to default 2

MDN's documentation states this quite clearly:

To be idempotent, only the state of the server is considered. The response returned by each request may differ

With regards to PUT - from the idempotency standpoint, the only thing that matters in the end state of the object.
Whether the server checks the current state of the object, blindly overwrites it, or does something else is inconsequential. As long as at the end of the request's processing the state of the object matches the state described in the request, the handling is considered idempotent.

With regards to DELETE - as noted above, the return value doesn't effect idempotentcy. The idempotent behavior dictates that the result of a DELETE request is that the object referenced by it should not exist once the handling of the request is done, whether or not it was there to begin with.
Personally, I'd return a 404 for deleting an object that doesn't exist, but as noted, the behavior will still be idempotent whether you return a 404, 200, or anything else.

should the server overwrite the resource every time, or skip the write operation if the data is unchanged?

That's an implementation detail, and therefore entirely up to you.

HTTP does not define exactly how a PUT method affects the state of an origin server beyond what can be expressed by the intent of the user agent request and the semantics of the origin server response. -- RFC 9110

There's is, I think, an important note in the section of the specification on conditional requests (specifically If-Match)

if the request is a state-changing operation that appears to have already been applied to the selected representation, the origin server MAY respond with a 2xx (Successful) status code (i.e., the change requested by the user agent has already succeeded, but the user agent might not be aware of it, perhaps because the prior response was lost or an equivalent change was made by some other user agent). -- RFC 9110

The general principle here is that HTTP constrains what the messages mean, but it doesn't really constrain your choice of which message to send.

PUT /example
Content-Type: text/plain

My new message

200 OK
Content-Type: text/plain

Status-of-the-action: that was a no-op

See also Fielding 2002-04.

---

For PUT: If a client sends the same PUT payload multiple times, should the server overwrite the resource every time, or skip the write operation if the data is unchanged?

There's absolutely no requirement that the lastUpdated column in your database has to change when the body of the PUT request matches / is equivalent to the current representation of your resource. A No-Op is fine, and you can use a 2xx response code.

---

If a client sends a DELETE request for a resource that no longer exists, should the server return

Sending a 2xx response is fine, but a 404 might be better, if you have strong reason to believe that the identifier of the target resource doesn't make any sense. IE: you might prefer a 404 response when you think that the request URI has a spelling mistake.

A 410 response if the lifecycle of the resources ended so long ago that the client shouldn't even be thinking about it

The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. -- RFC 9110

---

204 No Content (to treat it as a success, since the desired state is achieved)?

Make sure that you understand the difference between a 204 response and a 200 response with Content-Length: 0, and choose appropriately.