What RESTful HTTP request for executing actions on the server?

Question

I have a RESTFul server API which I've built. Some parts of it is not controlling resources and I'm having trouble mapping the relevant URL + HTTP-method to the actions that are executed on the server.

e.g. I can backup every resource on the server with POST /backup, but I'm not sure if this the most appropriate mapping. What about a single resource? Should I specify it with: POST /backup/id or by declaring the id as a variable that I send: POST /backup <id>

Please give me some tips on how to structure this most appropriately so that my API is easy to grasp.

Answer 1

This depends if you create a new backup object on database each time you call, or if you have many backup objects (that is, backups for different files, for example) that hold only the last value.

POST /backups is used to create a new object, and so the correct answer if you always create a new backup.

PUT /backups/id if you are updating your backup data in the same object.

Answer 2

I believe POST /backup (to backup all resources) and POST /backup <id> (to backup a single resource) are going to suit you best here.

CRUD MAPPING: Like Ray said, backup doesn't map to CRUD well; you want an action resource on the server to perform the function. Mark Massé wrote the O'Reilly book on REST API design and his recommendation is to use an action resource on the server in that case (see slide 20 on the Action archetype).

URI DESIGNATION: Action resources should be the last segment of the URI with no child resources. This will make sense when you see the reason below for which HTTP method is best suited here.

HTTP METHOD: Backup shouldn't be an idempotent action, so you want the HTTP method that's not idempotent. That's POST. Not only is PUT idempotent, the URI you specify is where you're putting the resource you're sending. You don't want to do that if you want to be restful. Part of the purpose of POST and its non-idempotence is specified as

providing a block of data, such as the result of submitting a form, to a data-handling process

which is what you want here.

REST: To be a layered system, the server (by way of its action resource (the backup method)) should specify where its output should go; the client shouldn't house that logic.

---

So, doing it this way, your backup action resource is free to determine where you want to put the backups (which may be a store resource (/backups); see slide 19) and whether you want to overwrite the previous backups or whether you want to implement some form of version control (something that REST design doesn't account for). So basically you were on the right track!