Non-CRUD operations in a RESTful service
What is the "RESTful" way of adding non-CRUD operations to a RESTful service? Say I have a service that allows CRUD access to records like this:
GET /api/car/123 <- Returns information for the Car object with ID 123
POST /api/car <- Creates a new car (with properties in the request)
PUT /api/car/123 <- Updates car 123 (with properties in the request)
DELETE /api/car/123 <- Deletes car 123
POST /api/car/123/wheel/ <- Creates a wheel and associates it to car 123
If I want to change the car's color, I would simply POST /api/car/123
and include a POST variable for the new color.
But let's say I want to purchase a car, and that operation is more complicated than simply updating a "user" record's "owned car" property. Is it RESTful to simply do something like POST /api/car/123/purchase
, where "purchase" is essentially a method name? Or should I use a custom HTTP verb, like PURCHASE
instead of POST
?
Or are non-CRUD operations completely outside the scope of REST?
Think about purchase as a business entity or a resource in RESTful dictionary. That being said, making a purchase is actually creating a new resource. So:
POST /api/purchase
will place a new order. The details (user, car, etc.) should be referenced by id (or URI) inside the contents sent to this address.
It doesn't matter that ordering a car is not just a simple INSERT in the database. Actually, REST is not about exposing your database tables as CRUD operations. From logical point of view you are creating an order (purchase), but the server side is free to do as many processing steps as it wants.
You can even abuse HTTP protocol even further. Use Location
header to return a link to newly created order, carefully choose HTTP response codes to inform users about problems (server- or client-side), etc.
The RESTful way as I understand it is that you don't need new HTTP verbs, there's a noun somewhere that will mean what you need to do.
Purchase a car? Well isn't that
POST /api/order
What you're really doing is creating an order. So add another resource for order and post and put there during the order process.
Think in terms of resources rather than method calls.
To finalize the order you'd probably POST /api/order//complete or something similar.