我们可以将参数传递给 HTTP DELETE api

Question

I have an API that will delete a resource (DELETE /resources/{resourceId})

THE above API can only tell us to delete the resource. Now I want to extend the API for other use cases like taking a backup of that resource before deleting or delete other dependant resources of this resource etc. I want to extend the delete API to this (DELETE /resources/{resourceId}?backupBeforeDelete=true...)

Is the above-mentioned extension API good/recommended?

Answer 1

According to the HTTP Specification , any HTTP message can bear an optional body and/or header part, which means, that you can control in your back-end - what to do (eg see what your server receives and conventionally perform your operation), in case of any HTTP Method; however, if you're talking about RESTful API design, DELETE, or any other operation should refer to REST API endpoint resource, which is mapped to controller's DELETE method, and server should then perform the operation, based on the logic in your method.

DELETE /resources/{resourceId} HTTP/1.1

should be OK.

Answer 2

Is the above-mentioned extension API good/recommended?

Probably not.

HTTP is (among other things) an agreement about message semantics : a uniform agreement about what the messages mean .

The basic goal is that, since everybody has the same understanding about what messages mean, we can use a lot of general purpose components (browsers, reverse proxies, etc).

When we start trying to finesse the messages in non standard ways, we lose the benefits of the common interface.

As far as DELETE is concerned, your use case runs into a problem, which is that HTTP does not define a parameterized DELETE.

The usual place to put parameters in an HTTP message is within the message body. Unfortunately...

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

In other words, you can't count on general purpose components doing the right thing here, because the request body is out of bounds.

On the other hand

DELETE /resources/{resourceId}?backupBeforeDelete=true

This has the problem that general purpose components will not recognize that /resources/{resourceId}?backupBeforeDelete=true is the same resource as /resources/{resourceId} . The identifiers for the two are different, and messages sent to one are not understood to affect the other.

The right answer, for your use case, is to change your method token; the correct standard method for what you are trying to do here is POST

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

You should use the "real" URI for the resource (the same one that is used in a GET request), and stick any parameters that you need into the payload.

POST /resources/{resourceId}

backupBeforeDelete=true

Assuming you are using POST for other "not worth standardizing" actions, there will need to be enough context in the request that the server can distinguish the different use cases. On the web, we would normally collect the parameters via an HTML form, the usual answer is to include a request token in the body

POST /resources/{resourceId}

action=delete&backupBeforeDelete=true

On the other hand, if you think you are working on an action that is worth standardizing, then the right thing to do is set to defining a new method token with the semantics that you want, and pushing for adoption

MAGIC_NEW_DELETE /resources/{resourceId}

backupBeforeDelete=true

This is, after all, where PATCH comes from; Dusseault et al recognized that patch semantics could be useful for all resources, created a document that described the semantics that they wanted, and shepherded that document through the standardization process.