Non-CRUD operations in a RESTful service

Web ServicesRest

Web Services Problem Overview


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?

Web Services Solutions


Solution 1 - Web Services

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.

Solution 2 - Web Services

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

Solution 3 - Web Services

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.

Solution 4 - Web Services

I feel REST APIs help in lot more ways than just providing semantics. So cannot choose RPC style just because of some calls that seem to make more sense in RPC operation style. Example is the google maps api to find directions between two places. Looks like this: http://maps.googleapis.com/maps/api/directions/json?origin=Jakkur&destination=Hebbal

They could have called it "findDirections" (verb) and treated it as an operation. Rather they made "direction" (noun) as a resource and treated finding directions as a query on the directions resource (Though internally there could be no real resource called direction and it could be implemented by business logic to find directions based on params).

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionMikeWyattView Question on Stackoverflow
Solution 1 - Web ServicesTomasz NurkiewiczView Answer on Stackoverflow
Solution 2 - Web ServicesdjnaView Answer on Stackoverflow
Solution 3 - Web ServicesAndrew KothmannView Answer on Stackoverflow
Solution 4 - Web ServicesMaruthiView Answer on Stackoverflow