REST - revertable DELETE

Question

I have a question about HTTP DELETE and REST. I have a resource x. Depending on the state of x, deletion of x does either:

1. Delete x permanently.
2. Mark x as deleted. This means that x can reverted later on.

I assume that HTTP DELETE must delete the resource according to the HTTP/REST specifics, instead of marking it as deleted, for example: GET on x must return 404 after the HTTP DELETE has been processed. This means that HTTP DELETE cannot be used for the second situation. How would you model this delete behaviour (both 1 and 2) in a RESTful way?

Then, since some resources can be reverted, this should also be made possible via the REST API. How would you model revert behaviour in a RESTful way?

Let's assume x resides on http://company/api/x/ for simplicity.

Answer 1

You could use the trashcan approach.

DELETE http://company/api/x/

causes x to be moved to the trashcan. At which point it could be accessed with,

GET http://company/api/trashcan/x/

and if you wanted to restore it, then take the retrieved representation and do

PUT http://company/api/x/

---

UPDATE:

Using hypermedia makes it a bit more obvious to the client what they are supposed to do.

GET http://company/api/trashcan/x
=>
200 OK

<x-resource>
  <description>This is the object I deleted</description>
  <link rel="restoreto" href="http://company/api/x/" />
</x-resource>

Having thought about it some more, PUT is really the right method. It is unsafe, idempotent and you know the URI where to restore the file too. If fits the semantics of PUT perfectly. An alternative to rel="restoreto" might be rel="originallocation".

Answer 2

You have a resource that can exist in any of several states (active, marked_for_deletion, deleted) with actions that move the resource from one state to another. This is the classic definition of a state machine. For a given transition, you find yourself asking "what HTTP verb represents that specific transition? do I have to abuse one? is POST a catch-all? can I invent my own?" There is a better way. Expose the state directly, and use GET and PUT to modify it. Let the server figure out how to get from the former state to the new state. For example, you might have a resource:

GET /foo -> {"a": 1, "b": 2, "status": "active"}

You want to change it so that:

GET /foo -> {"a": 1, "b": 2, "status": "marked"}

You might well wonder whether DELETE is appropriate for that, or some custom method, or you can just PUT that new state and be done:

GET /foo -> {"a": 1, "b": 2, "status": "active"}
PUT /foo <- {"a": 1, "b": 2, "status": "marked"}
GET /foo -> {"a": 1, "b": 2, "status": "marked"}

Answer 3

RESTful means you can use POST to perform a delete if you wanted to since: Unlike SOAP-based web services, there is no "official" standard for RESTful web services.

In this case, I would change your Mark For Delete to a POST (it's actually an update and not a delete).