Restful way to delete a write-protected resource

Question

In my API, resources can be write-protected. Trying to DELETE such a resource will return a 409 (Conflict) response.

For users that are allowed to change the protected state of a resource, I want to introduce the option to delete protected resources with one request. How should this option be passed?

Possible solutions:

• Request body -- should not be used with delete requests
• Query parameter -- changes the URI, so technically refers to a different resource
• Custom header -- generally discouraged
• Standard header -- none apply
• Two requests -- not atomic, things could happen in-between (eg another user modifying the resource)
• Alternative endpoint -- not restful?

Related Questions

• In REST API, can DELETE methods have parameters?
  • Answer says yes to query parameters, but asks about deleting a subset of a collection
• REST, HTTP DELETE and parameters
  • Asks about a confirmation flag, answers say it should be handled in UI instead of API
  • Also says it violates the uniform interface principle, but doesn't explain why and how
  • Also argues that using query parameters would violate URI principle
• RESTful Alternatives to DELETE Request Body
  • Accepted answer says to use the body, but many commenters report technical issues
  • Query parameters are suggested as alternative, concern about URI principle is raised
• Is an entity body allowed for an HTTP DELETE request?
  • Says not to use the request body, even if technically allowed
• Whats the best way to design DELETE for a restful resource
  • Says to use query parameters, but again in a subset context

Answer 1

For users that are allowed to change the protected state of a resource, I want to introduce the option to delete protected resources with one request. How should this option be passed?

If the meaning of the request message is consistent with HTTP DELETE, then you should probably just use HTTP DELETE, rather than trying to invent a dialect that allows you to discriminate between DELETE and no-no-I-really-mean-it-DELETE.

Are your message semantics consistent with HTTP DELETE? You may want to consider this observation in RFC 9110

Relatively few resources allow the DELETE method -- its primary use is for remote authoring environments, where the user has some direction regarding its effect.

DELETE is the method token we send to a web server when we want that server to stop sharing representations of a resource. It's semantics are rooted in the transfer of documents over a network domain.

---

On the other hand, if the message isn't consistent with HTTP DELETE, then you should consider using HTTP POST.

POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009

---

Here's a way of thinking about the distinction: our goal in creating a "REST API" is to create a facade that disguises our domain service as an HTTP-aware document store.

If what the client is really doing is marking a document as hidden in the store; and as a side effect of that we may make a bunch of changes in our domain service, then DELETE is appropriate.

On the other hand, if what the client is really doing is sending information to our domain service, and as a side effect some documents are going to be hidden, then POST is appropriate.