> DELETE is not defined to be safe but it is defined to be idempotent
This one puzzles me though. How can DELETE be idempotent? If the first request works then the second one should return a 404, as the key to delete doesn't exist anymore.
Idempotency just means no state mutation on subsequent request.
Then you'd return 202 on a request to delete any invalid element, which really doesn't sound right.
> 200 with some sort of response to distinguish (e.g. { changed: boolean }).
Sounds even worse, and much like APIs that returns 200 with a payload saying {error:"not found"}
The key is the perspective of what success is: it’s the state where the resource does not exist, or is the action having deleted the resource. But 200/202 is perfectly capable of expressing the distinction in the latter case as well.
It depends on your use-case if you care about this or not. If you do care you will have to handle it either way somehow.
But if you want an idempotent API then a success is more appropriate IMO than an error.
It's the textbook definition of idempotence. So much so that wikipedia's article on idempotence mentions it and provides links to primary sources.
This is not correct. Safety and idempotency are two different concepts. Safety is when a request does not result in a state change. Idempotency is when the outcome is the same whether you make the request once or several times.
GET is defined to be both safe and idempotent. Clients can make GET requests without explicit human intent driving them because they are safe, not because they are idempotent.
DELETE is not defined to be safe but it is defined to be idempotent. This means you need human intent to drive it, but clients can retry as much as they like because whether you ask to delete a resource one time or a hundred times, the result is still the same – the resource is deleted. Obviously making DELETE requests can result in adverse effects even though it is idempotent.
POST is neither safe nor idempotent, however it’s subject to some unintuitive rules when it comes to things like cross-origin requests for historical reasons.