I wasn't aware of the distinction between “safe” and “idempotent”, TIL, thank you.
> 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.
HTTP requests are not RPC calls. The end state of a DELETE request is that the resource does not exist. If you make the request once, the end result is that the resource does not exist. If you make the request twice, the end result is that the resource does not exist. The spec. allows for the actual response to differ; the important thing is that the state is the same regardless.
Response is implementation detail: a 404 on second request is one way to do it, a 202 would be another, or 200 with some sort of response to distinguish (e.g. { changed: boolean }).
Idempotency just means no state mutation on subsequent request.
> 202 would be another
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"}
> Then you'd return 202 on a request to delete any invalid element, which really doesn't sound right
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.
Request failed successfully
It's the graphql way.
> This one puzzles me though. How can DELETE be idempotent?
It's the textbook definition of idempotence. So much so that wikipedia's article on idempotence mentions it and provides links to primary sources.