Context

We are developing a DELETE RESTFUL endpoint.

  • Calling this endpoint DELETE /book/1 for the first time when Book 1 is still on the server, Book 1 is deleted from the server, and the response is 204 👌
  • The second time the endpoint is called, Book 1 already does not exist. What should the second response be?
    • 404 because Book 1 doesn’t exist; OR
    • 204 because the caller (client) only cares that the resource has already been deleted

Research

This SO exchange was useful to clarify why this seems to be a contentious issue: Deleting a resource using http DELETE.

The sticking point for me is where the concept of idempotentcy should stop.

  • The state of the server for DELETE request is idempotent by nature, no problem.
  • Should the action that caused the idempotent effect on the server (the request from the client) be idempotent too?

Quoting RFC 7231 Section 4.2.2 below, with my emphasis:

4.2.2.  Idempotent Methods

   A request method is considered "idempotent" if the intended effect on
   the server of multiple identical requests with that method is the
   same as the effect for a single such request.  Of the request methods
   defined by this specification, PUT, DELETE, and safe request methods
   are idempotent.
Like the definition of safe, the idempotent property only applies to
    what has been requested by the user; a server is free to log each
    request separately, retain a revision control history, or implement
    other non-idempotent side effects for each idempotent request.
Idempotent methods are distinguished because the request can be
    repeated automatically if a communication failure occurs before the
    client is able to read the server's response.  For example, if a
    client sends a PUT request and the underlying connection is closed
    before any response is received, then the client can establish a new
    connection and retry the idempotent request.  It knows that repeating
    the request will have the same intended effect, even if the original
    request succeeded, though the response might differ.

PayPal preferred to extend the idempotency to the action.

My thoughts

In our context of initial discussion, we are creating a backend service that seems to expand its influence, and could be called by any client or other backend services, that could be beyond our control. Returning a 404 is also not wrong, as it reflects a more nuanced stance of accuracy.