Understanding the Definition and Philosophy of REST

REST is a controversial topic among Web service enthusiasts, because it’s considered to stand for the opposite of what Web services and SOA are trying to achieve. The problem with this thinking is that REST is not in contradiction with the abstract definition of SOA and Web services. REST is in contradiction with technologies such as SOAP, WSDL, and WS-* specifications. The following offers a quick definition of REST: REST is about database design, and SOAP is about API design. The definition in itself is controversial, as many point out that SOAP can be used to create document-basedWeb services. However, they miss the fact that REST does not refer to the data sent between the client and the server. It refers to how to address and send or receive the data. Let’s say you’re writing a SOAP Web service, which means you’ll be designing a WSDL document. WSDL itself implies the definition of an access point with operations, or in programming language terms, APIs. The APIs may support the transfer of documents, but the WSDL operations are APIs. This is not a bad thing, just a reference point to say that SOAP is about APIs. REST is about using the HTTP protocol to manipulate state indicated by a resource. The SQL programming language is used to manipulate relational data. In the SQL language, verbs, such as INSERT, SELECT, UPDATE, and DELETE, perform actions on the data. REST uses these verbs, but they’re HTTP verbs: PUT, POST, GET, and DELETE. Everything that you need to do to the data can be expressed in those verbs, regardless if you’re using HTTP or SQL. Another difference between database design and API design is that with database design, you’re working with sets.

The sets may have no, one, or many elements. The count does not matter. With APIs, the number of elements does matter, because you need to explicitly create APIs that manipulate either no, one, or multiple elements. None of these comparisons are meant to say that one is good and the other is bad. Instead, they are meant to illustrate that REST and SOAP are very different in their approaches. All of this theory sounds like hand waving, so the best way to explain the theory is to implement a service using REST. The example calculator application starts with a traditional API approach, converts the application into a preliminary REST approach, and then transforms the preliminary solution into a full-fledged REST solution. The preliminary REST solution is illustrated to demonstrate that not all REST solutions take advantage of all of the features of REST. The simple calculator only supports memory and the addition of two numbers. The server adds the two numbers together and generates a result. To add a new set of numbers, you need to click the Back button and enter two different numbers. From a processing perspective, represents the flow between calling the HTML page, sending the data to the server, and then generating the result. In a traditional Web application, when the user clicks the Submit button, the data from the HTML form (meaning the contents of the two text boxes) is gathered and sent to the server using an HTTP POST. The server reads and processes the data to generate the response in the form of an HTML page.

The results of the POST are fixed. This means that any HTML page with an HTML form can call the server-side generation page, but the result is predefined. In the example, the result has to be an HTML page that can be generated in an HTML page. The problem is that to generate a proper result, the server has to take into account style sheets as well as other look-and-feel attributes. If you think about it, the general purpose of the server-side POST is to generate a result to a query. Of course the server could employ some techniques to generate the correct data in the correct context. That has led to sophisticated frameworks that attempt to “fix” the problem of posting content. This is what makes Ajax such a compelling argument when developing Web applications. Ajax focuses on sending and receiving the necessary content, not the extra bits that have nothing to do with the content. When using Ajax, the initial page is still downloaded, but the nature of the HTTP POST changes. The same HTTP POST is sent, but the response doesn’t have to include HTML codes necessary to create a complete HTML page. When using Ajax, the HTTP POST changes into aWeb service call that asks for chunks of content to inject. The quirky Web application changes back to a traditional client/server application, where you can query and retrieve specific pieces of content.

When creating Ajax applications, how server-side logic is called becomes important. Imagine if the Ajax application were using a remoting technology such as Remote Method Invocation (RMI), Distributed Component Object Model (DCOM), or .NET Remoting. When using those technologies, a great deal of thought goes into which objects are exposed and how they are called. In an Ajax application, the same happens, except that instead of thinking in remoting terms, you think in terms of REST. REST is a way of organizing how to present data that the Ajax application can manipulate. Let’s go back to the calculator example and go through a preliminary version of converting the application into Ajax and REST. The browser uses HTTP and URLs to reference logic exposed by the server. The HTTP server itself doesn’t implement the logic, but instead uses the concept of a handler. A handler is a general cross-platform and language concept that is a cross-reference of a URL and some logic. For example, if the URL /services/calculator/ops is called, then the handler Calculator is executed. A single URL doesn’t have to be associated with a single handler. A handler could process multiple URLs, as is the case of the Memory handler. In a REST implementation, the important rule is that the URL defines the resource. A single URL cannot be used to expose multiple functionalities. Instead, a single URL can be used to expose multiple representations of the resource. In the case of calculator service /services/ calculator/ops, the format of the numbers to be added and the result depends on what the client indicates and the server can support. What is indicated and sent are HTTP headers in the HTTP POST. For comparison purposes, let’s consider how a SOAP-based Web service would expose its functionality. The SOAP implementation exposes a single URL, which is managed by a single handler. There are multiple implementations in the context of a handler.

The handler knows which implementation to call depending on the information sent to the URL. It calls the method add for addition, and it calls the method memory to store or retrieve memory. In the case of the memory retrieval, which piece of memory is stored or retrieved is a parameter. The data that is returned is packaged as a SOAP message. SOAP, in contrast to REST, offers multiple functionalities and representations in a single URL. Earlier, it was stated that REST is more akin to a database, and SOAP is more akin to an API. This is understandable because of the way each approach exposes its URL, and the data that is sent and received. The semantics of what the data is and represents at the URL is very different for SOAP and REST. In a REST approach, if you use HTTP PUT to save data on the server, then you assume to get the same data when calling HTTP GET. In a SOAP approach, if you use HTTP PUT, you don’t assume to get the same data when calling HTTP GET. In fact, using SOAP, you have no idea what data you’ll get, because SOAP requires some type of semantics that is associated with HTTP PUT and GET using a contract defined in a WSDL file. The difference between a database and API approach becomes clearer by evolving the calculator example.

Originally, the REST application used a set of URLs, but the URLs were wrong because they fitted an API approach on top of a resource approach. For example, the memory URL is /services/memory/1. The URL looks correct, but is in fact completely incorrect. As the URL is defined, the memory location /services/memory/1 is shared by everybody. To distinguish between the different users, most Web application frameworks use cookies. And cookies, again, are the completely wrong answer. Imagine writing an application where you save some value that you want to share with somebody else. If you give to the other person the URL that you used to store the data, that person could not access the data because his cookie identifier would not be compatible with your cookie identifier. The problem is that the state of the resource as defined by the URL is dependent on the URL and a cookie identifier.

This violates REST principles. REST principles state that if memory is stored at the URL /services/memory/1, then the same state is retrieved regardless of who accesses the URL. A cookie can be used for authorization purposes. Using a cookie, a server can identify whether a request is authorized to view the representation of the resource. The solution is to think in data terms and consider the memory location identifier as an arbitrary row identifier that references a memory location. This results in the addition being both a calculation and a memory operation. When writing your own REST application, remember the following points:

• REST is about managing data, and SOAP is about managing APIs.

• REST has dynamic contracts that is, the resources are connected and described using links and the HTTP headers of the client. For example, one client can define the contract to be XML data, and another can define the contract to be HTML data. The server adapts to each by sending an appropriate representation for a resource.

• REST has a set of predefined semantics using HTTP GET, HTTP POST, URLs, resources, and representations.

• SOAP doesn’t have a predefined set of semantics or contracts, as they’re defined by the metadata (WSDL).

• REST manages URLs in a dynamic manner, where URLs are created dynamically.

• URLs in a REST approach represent references to a resource and not necessarily a file on a hard disk.