Use HTTP DELETE Method
The HTTP DELETE method is used to request that the server perform a delete operation on the specified resource with resource specific semantics. Behind the scenes, the delete operation may result in a removal of a file from the filesystem, or an update to the database to reflect the change. Because multiple requests to delete the same resource has the same effect as a single one, the DELETE method is considered ‘idempotent’, but not considered safe.
[00:01] The HTTP DELETE method is used to perform a delete operation on the requested resource. I'm going to perform a delete. I have gist that I have starred as my user.
[00:23] Here, we can see that the DELETE method has been specified in the first line of my request. The server has responded with a 204 No Content response indicating success of my delete request.
[00:38] In addition to using 204 No Content without a response body, servers might also respond with 200 OK and include a message body with some more details about the successful request. Alternately, a 202 Accepted response may be returned. If the request to delete the resource has been accepted but not yet completed, it may take some time to perform that operation.
[01:03] It's important to note that the delete request relates to the resource identified by the URL. In the case of the GitHub API, the delete operation is performing some database update behind the scenes. To remove the fact that my user has starred this particular gist, other implementations may use delete on a particular resource to actually perform a file system delete behind the scenes.
[01:28] The HTTP DELETE method does not specify specifically the semantics of what is behind the scenes, merely the intended effect on the URL. It's important to note that the delete operation is item potent. I can resubmit this delete request and it will have the same intended effect.
[01:51] This allows both clients and browsers to resubmit a request if there is an error such as a network error during the processing of that request because the intended effect, deleting the given resource, is the same whether the request happens once or multiple times. You can see that even though I had already deleted the star in this gist, the server still returned me a 204 No Content response in response to my delete request.
[02:21] This may seem a little counterintuitive since a GET request on that same URL will return a 404 Not Found. This is because a delete on a resource that isn't necessarily there can still be considered success.
[02:39] To summarize, the HTTP DELETE method is used to perform a delete operation on a resource with unspecified semantics, meaning it might perform a file system delete or a database update in response to the request.
Would a DELETE action only be considered fully idempotent if it returns a 204 status code? If it would return a 202 or 200 with the body of the deleted item, I would imagine that won't be reproducible.