Self Learning : REST Services Design

I enjoyed reading the article How I Explained REST to My Wife and the closing of the dialogue “We’re trading simplicity for flashy tools and wizards”.  Let us start with REST Design. The biggest drive for REST web services is to make the ability to invoke easy for the clients. Given a web service requirement, the first step of REST design is to determine the objects to  expose and their respective representations. An object’s representation can be thought a set of properties.

Imagine an HR associate wanting to view stock WIPRO price and she typing in http://stockinfo/v1.4/stock/12345  in her browser’s address bar! One has to know that 12345is Wipro Id. Even if one does not know that, how about the URL: http://stockinfo/v1.4/stocks?name=WIPRO and get back a list of stocks whose names have "wipro" in them?

Note the words stock and stocks in the two URLs above. They are the resources. Resources are the objects exposed by the REST web service and accessed using the URL itself. In this example, the web service exposes two objects stock, representing 1 stock, and stocks, representing the collection of stocks. Instead of terming URL, these addresses represent URI-s. as in addition to locating a resource, they actually identify a resource

The representation of a resource is the state of a resource. If the representation changes, it is an UPDATE operation on that resource. The representation is typically returned in response to a GET. The representation of the stock object can be anything, including XML. Good REST web services also support JSON along with XML, but let us assume that it is XML for now.

Let us consider a guidelines that REST web service needs to perform as response to the HTTP verbs GET, PUT, POST and DELETE? Here are the guidelines:

  • GET: Return (retrieve) the representation of the resource identified on the URI. The request might not have a HTTP body. The response contains the object representation as the HTTP body, with specific HTTP headers set to certain values
  • PUT: Update the representation of the resource identified on the URI. The request sends the object representation XML as the HTTP body, and the designer can decide whether the client needs to send the entire representation XML on update, or just the elements that need to be updated. The response is recommended to have the the entire representation so as to reach back to client on successful update.

We see that both GET and PUT can act on a single resource stock/WIPRO in a standard, predefined manner: GET retrieved it, PUT updated it. Let us turn to POST.

In Rest, POST means create a new resource. How is it possible to have a POST request on some existing resource? The new resource to be created is not related to 12345(WIPRO). Where should the POST request go? What is URI? a REST request should act on the representation of the resource identified by the URI.

This is where the collection resource fits. We did, briefly, mention a collection resource when we were visualizing an investor fiddling with REST. A collection resource has its own representation, and is characterized by the fact that it does not need any specific instance to be accessed. In our example, let us expose the second object


This can contain individual representation of all stocks and if the stock representation of each stock is too large, we can define as follows

<stock id = ’12345’>
<stock id=12346> http://stockinfo/v1.4/stock/12346 </stock> 

This representation simply packs the URI-s of each stock in the collection instead of the full representation of each stock. The client then would need to issue GET commands for each stock (on their respective URI-s) to get the individual data back.

Looking at POST, The POST verb, in our example, should be allowed only on stocks resource. here the request contains enough information so that the service can create a new stock. And the response may either return the representation of stocks with only the newly created stock in it, or it may return the representation of the newly created stock. The response should have the id of the new stock in it. The response should carry the HTTP response code 201 Created (and not 200 Ok).

The DELETE verb is used to delete a resource. Now that we have two resources: stock and stocks, DELETE can act on either, but in order to act on stocks, it has to specify which stock to delete, which it can do by a query string id. But as designer of web service, designer can choose to allow operation only on one of the resources