109

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?

1
  • 6
    If you are changing a car's colour, it would be better to use PATCH /api/car/123 and send a colour parameter OR use PUT /api/car/123 and send the entire car object. POST would infer that you are creating a new car and should probably never include an id at the end of the URL Jan 12, 2017 at 11:10

4 Answers 4

68

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.

10
  • 3
    REST is all about manipulating the state of resources and every business operation has to be mapped to state CRUD operations. If you need hard business operations semantics, you'll have to go the SOAP way (SOAP is actually message passing, but is typically organized in request-response operations). Jul 27, 2011 at 20:35
  • 24
    The "purchase as resource" design looks neat. What if the resource is a "beer".. and I want the server to drink it.. ( it it was for me, I'd surely GET it ;) ).. should we consider the "drink action" as a resource ?!.. or is "drinking a beer", a hard business operation ?! More seriously, is the RESTful design about considering actions as resources ?!..
    – Myobis
    Feb 10, 2013 at 22:21
  • 2
    How would you expose "approve purchase order" through a REST service? I think @TomaszNurkiewicz is right in that anything that cannot be neatly done in a CRUD way will need the operation-semantics provided by SOAP. Unless "purchase order approval" is a model/entity on it's own. E.g. POST /po-approval (with PO details in the request). Feb 14, 2014 at 6:22
  • 3
    From the viewpoint of a REST client "approve purchase order" should just be another update of the order. E.g. change "Approved" to "true" and send the update to the server. The server will probably need to do a bunch of checks and probably it will need to update/create a bunch of other resources. But that's the servers problem and shouldn't be visible to the client.
    – AVee
    Jun 25, 2014 at 8:19
  • 2
    @antinome: "Suppose the client knows some of this", if that's the case you're not doing REST (it might still be valid, sensible software though!). REST was designed to be able to create clients which don't know that sort of thing, to create clients which still work if the behavior of the server changes. What you're trying to do is classic RPC, you either need to review your approach so it will fit REST, or accept that you are doing RPC and use a protocol intended for RPC like SOAP. REST tries very hard not to be RPC, so it's never going to be a good fit when you want/need RPC.
    – AVee
    Aug 26, 2014 at 11:59
15

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
2
  • 4
    Isn't PUT used to update resources since it's idempotent? This means you can call it as many times as you want, but only the first/last call is important. POST on the other hand is used to create resources and calling it twice should actually create two. Jul 27, 2011 at 19:46
  • 1
    @Tomas, yes, typo. Principle is important though, we're dealing with a new thing, an order, no need for a new verb.
    – djna
    Jul 27, 2011 at 20:11
5

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.

3

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).

2
  • 1
    That's a bad example. In this case the directions (all possible directions, infinite number of them) is the resource and the parameters are just filters. But you can't do an "purchase" with this, as filters only makes sense on get operations and putting an order or cancel it are operations that change the data
    – Tseng
    Oct 9, 2015 at 18:57
  • 2
    purchase would be POST to /order with a json in the body to indicate an order is created. cancel would be PUT to /order with a json carrying the order state change to indicate this is an idempotent update. I am still to run into an operation that cant be expressed in a resource format. So would be keen to see an example like that
    – Maruthi
    Nov 4, 2015 at 7:52

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.