The last week I’ve been busy, or shall I say lost in the world of RESTful Services. I have been reading white papers, watching screencasts, trying out the WCF REST Starter Kit on http://msdn.microsoft.com/wcf/rest and been totally amazed by the philosophy of RESTfulness.
Since I have been implementing SOAP web services for quite a while now, I have had a fairly ignorant attitude to the REST architecture up until the ASP.NET MVC Framework has gained popularity in the web development world. This along with me, just by a coincidence, stumbling into the WCF REST Starter Kit was enough to be convinced that REST really is the way to do it, developing services to be published on the web that is.
What is REST?
REST (REpresentational State Transfer) is a way of designing services, an architecture, to make machine-to-machine communication more intuitive than SOAP or RPC. REST is about organizing the resources to be exposed in a logical way, based on the structure of the resources. Don’t bother to define any operations or methods to be applied to the resources. In the RESTful world you are stuck with the basic HTTP operations:
- GET
- POST
- PUT
- DELETE
- (HEAD)
These methods may seem to be too few, but then think about SQL and its CRUD (Create, Read/Retrieve, Update and Delete) and what you can do with those.
Some examples
To gain access of a resource, exposed by a RESTful service, the Uri to the resource may look like this:
http://somedomain.com/article/123
This Uri is readable and may be entered in an address field in a web browser, and the expected thing will happen. You will get data about the article with an id of 123. Using a web browser to point out the Uri will cause a HTTP GET to be sent to the server and it will return some sort of representation of the requested article.
Let’s assume that you will have some kind of tool that will let you send an HTTP POST to the server with an attached article. In this case the article with an id of 123 will be updated with the submitted data. If the article was not in the data layer a new article would be created with an id of 123. The HTTP POST may in some cases be the same as PUT or vise versa, but it is up to the service developer to decide the allowed operations for the exposed resources.
The above maybe a little confusing so let’s give an example in a more organized way, more or less stolen from the REST page on Wikipedia (the example on the Swedish Wikipedia), http://sv.wikipedia.org/wiki/REST. Take a look at this together with the notes below:
| Uri (~ is the root of the service) | HTTP Op. | Result |
|---|---|---|
| ~/Product | POST | Creates a new product. |
| ~/Product/{ProductID} | GET | Returns the product with id = {ProductID}. |
| ~/Product/{ProductID} | PUT | Updates the product with id = {ProductID} with the submitted data. |
| ~/Product/{ProductID} | DELETE | Deletes the product with id = {ProductID} |
| ~/ProductGroup/{ProductGroupID} | GET | Returns a group of articles, where the group id = {ProductGroupID} |
- The first example, POST to the Uri ‘~/Product’ will create a new product and return the newly created article together with its id. If an id was supplied in the POST data the article would be created using this id.
- The second example, GET to the Uri ‘~/Product/{ProductID}’ will return the product with an id of {ProductID}. The product data is represented in some way, defined by the developer of the service and may be based on the type of client requesting the product.
- The third example, PUT to the Uri ‘~/Product/{ProductID}’ will be treated as an update of the product with an id of {ProductID}. The PUT operation is not supported by all clients and most REST services will handle a POST to the Uri given in the same way as if a PUT was submitted.
- The fourth example, DELETE to the Uri ‘~/Product/{ProductID}’ will delete the product.
- The last example, GET on the Uri ~/ProductGroup/{ProductGroupID} shows another way to organize the products. This is one of the advantages of REST, that a set of resources maybe exposed in many different ways and the meaning of the Uri along with the HTTP operation on the Uri are so easy to understand. The client to consume the resources is left with a really clean and easy to understand way to address the individual items.
Fundamentals
Since the basic HTTP operations are the way to retrieve and update data, the same way goes for the returned status codes of an operation. A status of 200 are to be interpreted as a successfully performed operation, a 400-405 means that the client submitted some erroneous request (’404 Not Found ‘ is well-known) and a 500 or 501 means that there was an error on the server side.
When it comes to security the built-in security features in HTTP may be used, meaning that the Authorization header is to be used.
One may suspect the following analyzing the examples stated above: Since basic HTTP operations are used when accessing the resources there maybe caching advantages using caching proxies and similar things. That is completely true and is one of the advantages with the RESTful way of designing services and organizing resources. Have a look at the links supplied below.
As you have noticed the well-known and well-defined standards of HTTP are used from top to bottom when designing RESTful services. Since HTTP is widely spread let’s look into loose coupling and nice interfaces below.
The loose coupling
As seen above no extra methods other than the well-known HTTP operations are allowed if the service will be a true RESTful service. Most of the web clients and programming languages around supports requests using these methods. This makes it possible to access RESTful services anywhere as long as a connection to the hosting application exists.
As you may have noticed, I haven’t mentioned anything about the actual implementation of the services so far. This is because of the simple fact that REST is not at all connected to any technique or programming language to be used when implementing the service. It is an architecture and a way to expose resources, not at all connected to the underlying system serving the interface.
With these two aspects on REST, no one around can say that REST is anything other than a philosophy when designing really loosely coupled systems, making machine-to-machine totally independent of the technique used when implementing the services. Since REST defines the HTTP basic operations the only operations allowed, any client supporting these operations may consume the resources exposed by the service.
Another important thing to consider is the fact that most of the HTTP clients will send an identification of the type of client, in the header sent to the service. This is really useful information to the service since it maybe used when composing the response data to be returned to the consumer. If the incoming request comes from an Internet Explorer based client, the service may decide to return an (X)HTML representation of the requested data, but some other client maybe receives an XML or JSON representation of the same data. This is completely up to the developer of the service to decide. In most cases XML is returned or maybe JSON, since it is easy to handle using Javascript or any other programming language floating around Internet and web sites nowadays.
Read more
The concept of RESTful services was defined in a dissertation by Roy Fieldning in 2000. The publication is found on http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm, REST is defined in chapter 5.
In the preface to this article a mentioned the WCF REST Starter Kit. This is a set of features and other stuff making implementation of RESTful services using WCF much easier. The project is run as an open source project on Codeplex, being developed as we speak. On the web site for the starter kit you can find a lot of useful information, white papers, screencast and things like that. Have a look at http://msdn.microsoft.com/wcf/rest.
On Wikipedia you will find a lot of useful information on this topic on http://en.wikipedia.org/wiki/Representational_State_Transfer, where you will also find bunch of links to other resources.
Stefan Tilkov have written a great article as an introduction to REST on http://www.infoq.com/articles/rest-introduction. He mentions the following “Give every ‘thing’ an ID” which is a key thing when organizing the resources. Read this article as it gives a great introduction on key aspects of RESTful services.
Since I’m totally blown away by the RESTful way of designing services and exposing data, I will most likely write more articles on this topic. I’m really looking forward to it actually. As soon as possible I will start to use the WCF REST Starter Kit in some kind of pre-production environment, just to try it out in a more realistic way other than just fooling around with it. I will write about the results here or on my development area, http://develop.freddes.se/blog.