In RESTful APIs resources are typically deleted using the HTTP DELETE method. The resource that should be deleted is identified by the request URI. DELETE is an idempotent HTTP operation. Sending the same DELETE request multiple times should only alter the server state once.
Deleting single resources
Single REST resource are usually identified by URIs containing a unique identifier. For example, we can delete the artist resource located at /artists/123 by sending a DELETE request to this URI.
Request:
1 | DELETE /artists/123 |
Response:
1 | HTTP/1.1 204 (No content) |
The server can respond to delete requests with different HTTP status codes:
- HTTP 200 (Ok) indicates a successful deletion with additional information. In this case, the response body can contain the deleted resource or some details about the deletion.
- HTTP 204 (No content) is used to indicate a successful deletion with no additional information (response body is empty).
- HTTP 202 (Accepted) is returned if the server accepted the request, but the deletion has not been completed. For example, the server might have queued the request to process it sometime in the future.
If no resource exists at the given URI a HTTP 404 (Not found) status code should be returned.
After a resource has been deleted, a GET request on the resource URI should return HTTP 404 (Not found) or HTTP 410 (Gone).
Deleting resource collections
The HTTP DELETE operation can also be used to remove all items from a resource collection. For example, we can delete all artist resources by sending a DELETE request to /artists.
Request:
1 | DELETE /artists |
Response:
1 2 3 4 5 | HTTP/1.1 200 (Ok){ "total": 321} |
In this example the server responds with HTTP 200 and a response body containing the total number of deleted resources.
If you want you can combine the delete operation with query parameters to filter the collection. For example, this might delete all orders that have been fulfilled before 2015-01-01.
1 | DELETE /orders?fulfilled-before=2015-01-01 |
While the deletion of all collection elements can be useful it is not common to support this operation. Before you provide this feature in your REST API, you should think twice if a client should really be able to delete an entire collection with a single request.
Request body and the DELETE method
Delete requests usually do not need a request body. However, in rare situations a delete operation might need some additional instructions beside filter parameters that should be transported as payload body.
The HTTP RFC 7231 describes the usage of the payload body for the DELETE method like this:
A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request
On Stackoverflow you can find a lengthy discussion if the request body can and should be used for DELETE requests.
In my opinion it should be avoided to use the request body for HTTP DELETE operations. It is generally unexpected and might produce hard to track issues with certain technologies. As a workaround a POST request to a separate resource can be used.
Summary
Using the HTTP DELETE method we can delete resource within a REST API. When necessary the DELETE method can also be used to delete entire collections. Services usually should respond to delete operations with 200 (Ok), 202 (Accepted) or 204 (No content) response codes.
Published on Java Code Geeks with permission by Michael Scharhag, partner at our JCG program. See the original article here: REST: Deleting resources Opinions expressed by Java Code Geeks contributors are their own. |
