Chapter 22: REST

In the Web Services family, SOAP is the "cool kid" that gets all the attention, but REST is the child that gets work done quietly in the background. REpresentational State Transfer (REST) is the Web Service for the rest of us. Apart from the fact that the acronym needs work (it was coined for a PhD dissertation), REST is really just a description of how the Web works: by moving (transferring) from page to page (the state). Each page you visit is the representation of that state. REST is all about simple links and using simple messages and query strings to get the job done.

Although the process of REST may not be obvious with the general Web pages you visit, think about a shopping site. You browse through a list of products, changing the state of the application and the representation of that state in your browser. Finally, you find the item you've been dreaming of for so long, and you click the link to buy it. State is added to an invisible shopping cart. Viewing the cart's contents is another click away. Increasing the quantity of items purchased is a matter of setting the number, and clicking an Update button. Deleting is just as easy. Everything is managed through simple GET and POST requests. You get many of the benefits of SOAP without having to build SOAP requests, understand WS-something-or-other, or process WSDL. Instead, you define the XML you'd like to pass between client and server.

Introducing the Basics of REST

Some users accept this fairly strict definition of REST, but many others consider any Web service that can be accessed using simple GETs or POSTs as being REST. To differentiate these two camps, I'll refer to these two concepts as pure REST and just-enough REST.

Pure REST

In a pure REST system, resources are the entities exposed by the service: the products you sell, the customer records you view, the pages you interact with. Each resource should have a unique URL that defines it, such as http://www.mysystem.com/products/5323. Accessing that URL using an HTTP GET request should return a representation of that resource, in this case a block of XML (or XHTML). In a pure REST system, GET requests cannot change the resource. Changes are performed by other HTTP verbs, as outlined in the following table.

Open table as spreadsheet

HTTP	Verb Action
GET	Request for a resource. No change is made to the resource. Returns an XML representation of that resource.
POST	Creates a new resource. Returns an XML representation of that resource.
PUT	Updates an existing resource. Returns an XML representation of that resource.
DELETE	Deletes a resource from the system.

Those who do a lot of database programming should see some familiar items. These four actions map closely to the common CRUD (Create, Retrieve, Update, and Delete) that are done in database applications. Although these are not exact matches by any means, it is good to keep this relationship in mind when planning your own REST services. Just as your SELECT statements do not actually change your database, GET posts to a pure REST service should not change any data.

Just-enough REST

In a just-enough REST system, only GET and POST (or even just GET) URLs are used. In this model, all the operations of the service can be accessed via a query string in a browser. Part of the rationale for this is that many clients do not support the PUT and DELETE verbs, leaving GET and POST to perform multiple duties.

The Danger of GET

Many people attempt to define just-enough REST interfaces that use nothing but GET requests, rationalizing that this makes testing easier, because the user can type all URLs into a browser to make them work. (You'll sometimes see this referred to as the queryline or url-line.) This method is fine if your service is read-only; however, it can lead to many problems if you provide for other CRUD calls using GET requests. For example, imagine having a URL like: http://www.example.com/products/delete/42 or http://www.example.com/products.aspx?delete=42. Although this would be harmless and possibly useful when used correctly, remember that this URL could be saved as a bookmark-or worse, recorded by a search engine or Web crawling application. After it is saved, this URL could be accessed again in the future, with possibly disastrous results. For example, Google produced a product called the Google Web Accelerator. Its noble aim was to make Web browsing faster by pre-downloading the links from pages you view. It did this by accessing all the links (using GET requests) on the page in the background. Now imagine what would happen if you view a page that contains links to delete URLs? To avoid the embarrassment of losing all your data, remember: GET requests should not change the data and have no side-effects.