Restful Webservices

This article is about Restful webservices and some thoughts on its design/architecture.

REST stands for Representative State Transfer. Restful architecture is resource oriented. The services expose a set of resources to the client and client can perform a set of operations on the resources which modify the state of the resource.


Restful webservices design requires a paradigm shift in the way we think about designing services. In the SOAP world, it was all about operations. So we used to think, what will this webservice "DO". But that is something which we should not do in Restful. 

Let's take for example an order entry application. In the SOAP world, we would think about services like createOrder, updateOrder, addLineItems etc. To design the same in Restful world, we need to identify all the resources in the application which the client cares about. These resources need not necessarily have a one to one mapping to the underlying schema. It is just the resources which matter to the client.

In our example, the resources could be Order, LineItem, Customer etc. We also need to establish a hierarchy amongest these resources for eg.,  Customer -> Order  -> LineItem. 

How to identify the resources?

The resources are identified by using URI. The URI should be something like a directory structure listing so that the client will not have  too much of a trouble to guess the URI. The URI could also embed identifiers to pin point to a particular resource. For eg, an order ID, a customer ID etc.

In our example, the URI to identify an order with an order ID of 1000 for a customer Paul could be something like: http://www.orderentryapp/resources/customers/customer/paul/orders/order/1000/

Note that we could easily guess the hierarchy and drill down to the particular order. Removing /order/1000 will return an URI:

The above URI will identify all the orders ordered by paul.

How to operate on Resources?

So, how can the client operate on these resources. Restful relies on HTTP protocol and uses the standard GET,PUT,POST,DELETE operations.

GET - Retrieve a resource (eg., It retrieves the order with order ID 1000)

PUT - Create/update a resource (completely replace existing) when you know the URI which will be created/updated

POST - Create a resource when you do not know the URI which will be created

DELETE - Delete a resource. However, this will require proper authentication of the client to prevent unholy deletes.

HEAD - Identical to GET except that the server MUST NOT return a message-body in the response. HEAD should be used to return meta data about the resource returned by GET. Clients can cache the results of HEAD. For eg, HEAD could be used to check if a resource exists or the last modified date
For PUT/POST - The client can send parameters as HTTP post parameters to create/update the resource.

Now, there is an argument over usage of PUT vs POST. 

PUT requires the operation to be idempotent, while POST does not. 
i.e, multiple invokes to PUT the same resource should result in the same outcome.

Let me explain this in more detail:
The URI in consideration is: http://www.orderentryapp/resources/customers/customer/paul/orders/order/1000

Now a PUT request to the above URI, should create a new order with an ID of 1000. If an order already exists with ID of 1000, the resource should get replaced with the data provided in this request. So, no matter how many times we invoke PUT for ID of 1000, the outcome will always be an order with ID 1000. That is idempotency.

Now the definition of POST says that, POST should be used to create a child resource as well as the URI. i.e, the client is not aware of the URI being generated. 

1. Usecase for POST:

Client says "Create an order for me and return me back an ID which I could use in further requests".

So, a POST to http://www.orderentryapp/resources/customers/customer/paul/orders/order will generate an Order with ID (say) 1000 and it will also create an URI
Subsequent PUTs to the above URI will update the order with ID 1000. So, POST could be used to create orders when the server will generate unique IDs rather than client specifying the IDs.

2. Usecase for PUT:
Client says "Create an order for me with ID 1000 and I will use the ID 1000 for further requests". Note that here, 1000 need not be the primary key on the server side. That detail is hidden from the client. The server might generate its own primary Id and correlate it to 1000. All that the client cares is that, it should be able to get/update using that ID.

How to handle errors?

Exception scenarios could be handled by returning HTTP error codes like 400,404, 403 etc.

What are the Response formats?

RESTful services can return XML, JSON etc which is driven by the HTTP accept header.

Also, an interesting point to note is that we can also return URIs in the response. Let's say after a POST to create a new order, instead of returning an ID, we can return the new URI, which could be used by the client for further GET/PUT requests. This can be done by returning the URI in the location header. For eg., Location: /order/1000


Now the final question. Should I use SOAP or REST? The answer really depends on the use case. Ask yourselves these questions:
 1. Am I able to identify resources in my system? 
 2. What is the nature of service expected by the clients of my service? 
 3. Is my system an operation engine or a resource driven system? For eg, systems like billing engine, or  tax calculation engine are more of service driven which may not fit the Restful bill.

Note that Restful clients are extremely simple to build when compared to SOAP clients which involve complicated bindings and infrastructure plumbing code. A well designed SOA application can have a combination of REST as well as SOAP based services.


Popular posts from this blog

Pivotal Cloud Foundry (PCF) Integration with Elastic Cloud Storage (ECS)

Restful code example using Spring MVC

Spring Integration - Bulk processing Example