DELETE method

The HTTP DELETE method removes content. With a selector range unit it removes one element and all its descendants; without a selector it removes the whole document.

When to reach for it

Use DELETE to remove a fragment from a document, or the whole document. The server returns 204 No Content — for a selector-scoped delete, with a Content-Range header identifying the removed element.

All DELETE requests are subject to authorization.

Examples

Remove an element

Remove the last paragraph from a document:

DELETE /delete-remove-test.html
Range: selector=p:last-child

HTTP/1.1 204

Verify the removal

Reading the document back confirms the element is gone:

GET /delete-verify-test.html

HTTP/1.1 200

<!DOCTYPE html>
<html><body>
  <h1>Title</h1>
  <p>Keep this paragraph.</p>
  
</body></html>

Delete a whole document

A DELETE with no selector removes the entire document:

DELETE /delete-whole-doc-test.html

HTTP 204

A later GET for that path returns 404 Not Found.

Concurrency

A whole-document DELETE can be made conditional with If-Match, exactly as for PUT: send the ETag you last read, and the delete only succeeds if the document is still at that version when the delete commits. If another client changed the document in the meantime, the DELETE is rejected with 412 Precondition Failed (with the current ETag in the response) instead of removing a version you never saw. The single-tag, list, and * forms of If-Match all work as they do for PUT.

Error cases

Condition	Status
Document does not exist	`404 Not Found`
Selector matches no element	`416 Range Not Satisfiable`
Authorization denied	`403 Forbidden`
Schema validation fails	`422 Unprocessable Entity`
Selector-scoped delete on a collaborative document can't be reconciled	`422 Unprocessable Entity`
`If-Match` ETag no longer current (document changed concurrently)	`412 Precondition Failed`

Absence and denial are distinct. A selector that matches no element gets 416, and one you are not permitted to write gets 401/403 — the two are never confused. Where the edge cannot see your target it re-checks against the live document before answering, so a 416 means the element really was absent at that moment. Two cases still refuse rather than reporting 416: a target that exists but is covered by a rule denying it, which is a genuine authorization answer rather than an absence; and a target you would not be permitted to read, since "there is nothing there" is itself information about the page. If you can write to part of a page you cannot read, writes refuse identically whether the target exists or not.