REST vs. SOAP

There is a lot of information on the web pertaining to REST; however, there is nothing relevant that compares REST to SOAP. This post contains a brief introduction to REST, and provides a REST vs. SOAP comparison. The reader is expected to have some familiarity with SOAP.

REST(Representational State Transfer) is an architectural style for networked applications, which is based on the Ph.D. dissertation of Roy Fieldings. REST introduces a different paradigm for web services, which are traditionally thought of as a RPC-based services, using a SOAP+WSDL combination. Web services written using the REST style adhere to the Resource Oriented Architecture (ROA) paradigm, a term given to a set of rules for designing such services. Typically, a user of a web application progresses through a series of pages or URLs, resulting in the state being transferred from one traversed resource to the next. REST attempts to formalize this model using four important concepts - resources, their names, their representations and the links between the resources. All RESTful services are judged by four important properties – addressability, statelessness, connectedness and the uniform interface.

REST architectural rules are also called “constraints”. Unconstrained architecture allows method calls, RPC and other messages that are understood by a specific component or module (client or server) involved in the interaction. REST eliminates ad-hoc messages and radically shifts the focus of API development towards defining pieces of information that can be retrieved and manipulated. The motivation for REST was to create an architectural model for how the web should work, such that it would serve as the guiding framework for the web protocol standards. REST prescribes the use of standards such as HTTP, URI and XML.

REST objects are called “resources”, with the information in resources being called “state”. This information has to be encoded to include it in a message, this encoding are called “representation”. Method invocations transfer state in representations. The following is a list of the HTTP methods and their implied meaning in REST:

· GET to an identifier means, give me your information.

· PUT to an identifier means, replace your information with the new one provided.

· POST adds new information.

· DELETE removes the information.

Resources are identified by URIs and manipulated through their representation. HTTP is a compliant RESTful protocol; however, it is possible to apply REST concepts to other protocols and systems. The statelessness property of REST ensures that any resource can be served by any server, thereby making REST solutions highly scalable. REST services may be described using WSDL or WRDL (Web Resource Description Language). The following are the characteristics of a REST-based system:

· Client-Server: A pull-based interaction style.

· Stateless: Request from client to server must contain all the information necessary.

· Cache: To improve network efficiency, responses must be capable of being labeled as cacheable or non-cacheable.

· Uniform interface: All resources are accessed via the generic HTTP methods.

· Named Resources: Every resource in a RESTful service is appropriately named.

· Interconnected resource representation: Enables a client to progress from one state to another.

A logical question is: how is REST different from SOAP? SOAP offers a RPC-oriented paradigm, where the participating components are interacting in a closed environment, using a proprietary API. REST offers a solution based on commonly used web standards and offers a more open solution, where even unknown clients can connect to a server component and use its capabilities using standard HTTP requests / responses. In addition to this basic difference in the two approaches, the following are some additional differences between these two paradigms.

· Security: A proxy server can look at the REST request and determine the resource being requested, based on which the request may be allowed or denied. Whereas for the SOAP message, the resource is identified inside the envelope, which is not accessible, unless the SOAP message is written using RDF (Resource Description Framework) or DAML (DARPA Agent Markup Language). Therefore, for a SOAP-based web service, security is generally built into the proprietary API.

· State Transitions: Each resource representation received by the client causes it to transition to the next state. The decision about which link to navigate is either hard-coded in the client or determined dynamically using XLINK (xlink:role). In a SOAP network, state transitions are always hard-coded in the client.

· Caching: Network communication has always been a bottleneck, and therefore the HTTP headers can contain a request to cache data. SOAP is always a HTTP POST and since the SOAP URI is directed to the server and not the resource, no caching is possible with SOAP. However, since REST uses the generic HTTP interface, it is possible for intermediate proxies to cache the results from a RESTful service call, in an effort to achieve a better performance.

· Evolving the Web (Semantic Web): It is envisioned that eventually the web will be accessed by people and computers alike, each being capable of intelligently processing the data returned by services on the web. In this vision of the Semantic Web, every resource has a unique URI and is accessible using standard HTTP methods. SOAP is not consistent with the Semantic Web vision, whereas REST is completely aligned with it.

· Generic Interface: Using REST, access to every resource is made using HTTP GET, POST, PUT and DELETE. With SOAP, the application needs to define its own proprietary methods.

· Interoperability: With interoperability, the key is standardization. Web has standardized on certain things, such as URI for address and naming, HTTP for generic resource interface and HTML/XML/GIF/JPEG for resource representation. REST uses these standards, whereas SOAP depends on customizations. SOAP clumping of resources behind a single URI is contrary to the vision for the web. SOAP is best utilized for closed systems, where all participants are known beforehand.

FindBugs Warning - Exception is caught when exception is not thrown

Performing static analysis of a Java code-base on a regular basis is an extremely useful exercise, and I have found FindBugs to be an extremely useful and worthy tool. One particular warning raised by FindBugs - exception is caught, when exception is not thrown - may appear to be a false positive at first, however, the tool basically recommends catching specific exception types, instead of having a "catch all" exception clause that catches the base Exception class.

The reason for this is pretty simple - catching the base Exception class will also catch the RuntimeException, which is a child class of Exception. This will mask potential programming mistakes. As a result of having a catch clause with the base Exception class, I have seen instances of NullPointerException - a child of RuntimeException - being caught and logged on numerous occasions. This potentially masks problems in the code, when an object instance was null, although it wasn't supposed to be so. If the object is null in only certain circumstances, then there is a distinct possibility that catching the base Exception will cause this problem to slip by in the development environment and fail in a production set-up at a customer site.

Catching specific exceptions and handling them appropriately - and perhaps differently - also makes for a better error-handling approach. Overall, it improves the readability of the code, where others are able to better understand and extend the exception handling mechanism.

Not long ago there was a trend among Java programmers to use the "*" notation while importing packages - e.g. java.util.*, instead of explicitly importing the classes required. This trend seems to have disappeared, and I hope that the trend of catching the base Exception class also cedes to the approach of explicitly catching the specific exceptions.