Note that idempotent in this context means “2 calls will end up with the same server state as one call”.
It does not mean for example that the second call can’t return a different response than the first.
It does not mean for example that the second call can’t return a different response than the first.
But REST's version of idempotency isn't good for this. If you retry your request multiple times (due to flaky connection or whatever), it only guarantees the same server state if your duplicate requests are bunched up.
For example if you do a DELETE then create it again with a POST, if there is a duplicate straggler DELETE floating around it will end up redeleting your new recreation.
Also allows you to implement optimistic concurrency. See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If...
"Do the same thing" isn't specific enough. Does it mean the state of the system? Does it mean the response code? Does it mean the response body? Does it mean all of these things? All seem like reasonable interpretations.
It doesn’t mean “do the same thing” or “get the same response”, only “end up in the same place”.
You can do a delete x, get an OK response, and the important state is that x is now deleted on the server. Then the next call to delete x does nothing (which is different from the first which deleted x!). So to be idempotent it has to do something different. The response in the second case can be both “ok” (because the thing is deleted) but also e.g “x doesn’t exist”.