DELETE
The DELETE method requests that the origin server remove the association between the target resource and its current functionality. It effectively unlinks the resource from the request-URI, the resource may still be available at another URI, or in revision control or backup systems.
Calling this method on a resource may remove other resources, too. Clients may encounter applications where resources removed from one set of resources will remove an equivalent resource from other sets. For example, calling DELETE on Alpha.json
file may also remove Alpha.html
.
However, DELETE should not deeply remove the resource from all the locations it is in. DELETE should not remove archival copies.
The behavior may also vary depending on which URI is deleted. If the server makes resources with particular tags available at a certain location, a DELETE from this collection should not remove the resource itself, but instead may remove the tag from the document.
Writing requests (clients)
The usage of DELETE is typically dictated by the origin server. Clients may look for an Allow header listing the DELETE method, that indicates the resource supports DELETE. Origin servers supporting DELETE will typically be APIs and remote authoring environments (for example, WebDAV).
Clients should send If-Match to ensure that if the document is changed by another party, these edits are not lost. Users may take some discretion in using this feature, you may not care if the document has further edits to it.
Clients should ignore 404 and 410 responses, or treat them similar to a success, since these indicate the resource is already gone.
Reading requests (origin servers)
Since the resource must first exist before it can be deleted, servers should return 404 and 410, if the resource does not exist, or is flagged as deleted.
Servers may wish to consider only allowing DELETE on a negotiated resource. For example, DELETE Alpha
will also remove Alpha.json
, but DELETE Alpha.json
would result in an error. In this case, the server should specify in the error description the equivalent resource URI that can allows DELETE.
Servers may implement this feature a number of ways.
Unlinking relevant records
The underlying record can simply be removed: The file can be unlinked, moved to an archive location outside of the document root, or the database record can be deleted. This will remove all variations produced from this resource; for example, if a server produces both HTML and JSON variations of a resource, then deleting one will delete the other.
Set gone/deleted flag
The origin server can tag the resource with a flag specifying that the resource is deleted. This allows the server to preserve the record in the server for administrative purposes, and to reply with a 410 status code to inform clients that the resource did previously exist. The resource may still be available in an alternate URI, for example, a collection of records. Deleting from this collection will normally be impossible, returning 403 (Forbidden).
Overview table
- Name
- DELETE
- Description
- Unlinks (removes) the specified resource.
- Specification
- RFC 5789: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. 4.3.5. DELETE