Wednesday, September 28, 2011

How to model RESTful Web Service

I see somebody lost way when he/she tries to model RESTful Web service. The issues I noticed are,
  • Not always keep in mind that RESTful Web Service is CRUD on "resources".
  • Put verbs in URI. Therefore, the concept about resources is messy up. 
  • Not think that URI is a hierarchy structure to help on organizing "resources"
 So, I made below picture to help on modeling RESTful Web Service.



Simplicity should be one of major reasons for us to adopt RESTful Web service. So, I think it is unnecessary to make RESTful model to be complicate. Another major reason to use RESTful Web Service is that the motivation of project is to "share resources" over the Internet/Intranet (or should say in Cloud? :) ). With these concepts in mind, we can divide the modeling process into four steps as below,
  1. Tell myself that I am going to make software to share "resource" as sharing HTML pages.
  2. Making a sheet to list/add resources into it.
  3. Check each resource and see if it need to be further categorized, Or, we will think if we need to have a reserved category for future. These categories will be mapped into URL. 
  4. For each classified resource, we can do CRUD operations, which maps to HTTP verbs POST, GET, PUT, or DELETE.
Using the Customer in above picture as an example, it is a kind of Resource. Customers are under different categories, silver and gold. For each customer, we can do CRUD operation. Then, the URI for getting a customer may like this: /resources/customer/silver/customerID/

It is better to avoid putting verbs in URI because we are going to share resource and verbs (operation) will be indicated by HTML verbs. Of course, it will still work if we put verbs in URI. It is just string. There is no standard spec for RESTful Web Service. We can define our own languge/protocl in URI. But, what I introduce here should be helpful for organizing analysts' thoughts and make models to be neat and SIMPLE.

No comments:

Post a Comment