Practical REST services design questions

Question

I am working on a project whose current stable version is written using JSP/Servlets and it needs to be re-written as Single Page Application using client side MVC framework Backbone.js and REST services on server written using spring web MVC. Same set of REST services should be used for iOS application written using Objective C.

This is the first time I am writing non-trivial REST services and I have gone through a book on Rest and many blog entries as well as many StackOverflow entries like following:

• Non-CRUD operations in a RESTful service
• Best practice for partial updates in a RESTful service
• REST practices for validating a resource
• http://abstractfinal.blogspot.in/2007/04/restful-urls-for-non-crud-operations.html
• http://www.infoq.com/articles/designing-restful-http-apps-roth

I have not yet found any definite answer to all of my questions which I encountered during design of the REST services. I have done design of those services but I want to validate my design.

1. My application has Car as a main resource. So my URI to get all cars becomes something like

   GET http:/host:port/mywebappname/cars
   

   URI to get a particular car is

   GET http:/host:port/mywebappname/cars/MH12-1234
   

   where MH12-1234 is id of the car.

   My trouble begins when I want to get all such cars those are manufactured by Ford and Hyundai in 2010. Probable URI in my opinion becomes either

   GET http:/host:port/mywebappname/cars/search/Ford;Hyundai/2010
   

   or

   GET http:/host:port/mywebappname/car/search?make=Ford,Hyundai&year=2010
   

   1. Which one of these is right?
   2. I could not imagine "search" as resource so I am keeping car as resource and search as a operation on it. Is this against REST ideology?

2. My car resource has many possible operations, e.g. painting a car, washing a car etc. URIs of those operations look like following to me.

   POST http:/host:port/mywebappname/cars/MH12-1234/paint/yellow/glossy
   

   or

   POST http:/host:port/mywebappname/cars/MH12-1234/paint?color=yellow&finish=glossy
   

   1. Which one of these is right? and should I send entire car object as a part of request body?
   2. Some people suggest that operation name should be sent as custom attribute of request header. So in my case paint will go inside request header. In such case, where do I send information like color=yellow and finish=glossy? As a part of request body or header?

3. Once client reads the car resource, it may want to change its wheel to some other suitable wheel. So URI for this operation may look like

   GET http:/host:port/mywebappname/car/MH12-1234/replace/wheel/rear-left
   

   This is basically replacing rear left wheel with some other suitable wheel.

   1. Is this right approach?
   2. Should this service return entire car or just the new wheel?

4. User who is playing with the car object in the client interface may try various operations on the car. E.g. user may paint it yellow and then paint it green and replace multiple wheels and then ultimately click on save. For each action that user initiated I have to post the entire car object or part of it to the server. So is it OK to send the part of it to avoid package size on the wire?

   Now those request are sent as either PUT or POST and server carries out those operations in memory and returns modified car object. Now car resource is getting sent as request and car object is received as response. Is this a valid scenario?

   If yes, then in both cases (save button click or any operation) I have to POST or PUT the same car resource to the server. I want to actually save car resource to database when save button is clicked and in case of other operations I just want to carry out the operation in server memory and return modified resource. How do I differentiate on the server about the user clicking on save as in both cases I PUT or POST the resource?

Answer 1

Try to avoid using operations.

Just modify attributes of your car client-side and do a PUT to save changes.

Server-side should then verify if it's coherent (like do not put a paint instead of gas) and saves or eventually return a HTTP error.

For searches / filters, I like this approach.

Anyway, REST is more of a general guideline and you don't need your API to follow REST principles literally.

Do what you think is more logical for your data, following REST guidelines, not constraining your API to it.

Answer 2

Try to think in REST services like http resquest, so

1. I will choose GET http:/host:port/mywebappname/car/search?make=Ford,Hyundai&year=2010 because is more similar to GET request. Also try to think in a request for all the cars of year 2010 with the other format GET http:/host:port/mywebappname/cars/search//2010

2. The correct will be send POST http:/host:port/mywebappname/cars/MH12-1234 and in the body of the post the information of the request, in the format thar to choose, the usual is xml o json. My advise is that you must use another url for this service, something like http:/host:port/mywebappname/service. Try to isolate the urls: cars must be for serach cars or add a new car, not for an appointment at the garage operation.

3. the best in this case is use a PUT service, that in REST is add or modify an item, but usually is used only as modify an item, and is simillar to the POST services: PUT http:/host:port/mywebappname/cars/MH12-1234 and the modifications in the body.

4. Depend that you want: if the web is for buy cars, maybe you you only must add a new car when the selection is finished; if is for a garage an the modifications implies send the car to the garage, maybe must be another service and when the car is finished that the mechanics modify the car.