Reusability and distribution of logic to self-contained units have been the driving force behind the development of technologies such as DCOM and CORBA. However, complexity and platform dependency have marred these from being standard technologies for creating and consuming distributed and reusable systems. That’s why concept of Web Service came into prominence. Since, it is based on XML and HTTP, Web Services soon became most used standard for implementing distributed systems that cut across languages, platforms and technologies. There are two types of Web Services – SOAP based and REST based. This series of posts will focus on developing Web Services based on REST using Java.
REST is short for REpresentational State Transfer. This post concentrates on the whys and wherefores of REST. First section would focus on the basics of REST. The second section would be about difference between SOAP based Web Service and REST based Web Service. The last section would introduce Resteasy that can be used to develop REST based Web Services.
REST – the whys and wherefores
REST, short for REpresentational State Transfer, is an architectural principal using which we can develop stateless web services that can run over HTTP and clients developed in different languages can access them just as they access any other web page. In REST, every object accessible via HTTP is a resource and each of these resources can be accessed via a Uniform Resource Identifier or URI.
If you consider the full form of REST, there are two main parts – representational and state transfer. The former relates to the resource itself and the latter relates to the client. Let us say, for the sake of example, there is a library management service that can be accessed using the following URI http://library.contessa.com/rest. It contains a resource 1695 that provides details of a particular book. Clients can access it using the URI http://library.contessa.com/rest/1695. The response is in the form of an HTML page. The HTML page is a representation of the resource 1695 which is provided by the service. The resource can have many representations – HTML, XML, JSON etc. Once client receives the response, which in our example is HTML, places the client in one state.
Next, let’s say the HTML contains a link to another resource – the details of the author. If the client traverses to the author resource using the link, client is placed in a different state. So, in short, whenever the client traverses to different resources or different representation of same resource its state is transferred from one representation to another. Hence, the term REpresentational State Transfer is used for such services that are centred on resources, representations and state changes.
Now that we have the basic concept behind REST, let us look at the most common terminologies used in REST, which are:
- Resource: Anything that can be accessed using URI is termed as a Resource. Scripts that return records from database, images, web consumable slides etc. can be an example of a resource.
- Representations: Representation means in what formats a client can request a resource. If a Resource can be represented as XML and HTML both, then XML and HTML are its representations.
- Methods: The way by which client communicates with the server to perform certain operations is define by Methods supported by the resource. Since, REST uses HTTP as the protocol for communication, so a resource can support all or subset of the methods provided by HTTP. For example, in HTTP you can use GET, POST, PUT, OPTIONS, DELETE and HEAD methods. It is up to the resource whether or not to support all of the aforementioned methods.
- Messages: Each request and response is a message. One important point to keep in mind is that the messages should be self-contained. For example, a response containing the details of a resource with id 6743 should contain everything related to that resource. Client need not to wait for a second response to have complete data about the same resource.
- State and session: The currently sent representation is the State of the resource. If the client needs to track what was the state before the current one, it will need to take implement session at its end. In REST, server is only concerned with the state of the resource and not of the client.
So, if we want to define characteristic features of REST on the basis of what we have discussed so far, the features will be:
- It is an architectural style and not a framework or toolkit.
- It is not a standard. However, it uses standards for communication (HTTP), representations (XML, JSON) etc.
- It makes use of pull based client-server interaction style. Client requests (pulls) a representation of a resource from the server. Server does not send the representation unless a client asks it for the representation.
- It is stateless. That means server does not keep track of the requests it receives. It is client’s responsibility to provide all the required information in the request.
- The responses are cacheable. The server must mark each response as either cacheable or non-cacheable so that client can take advantage of caching mechanisms to improve performance.
- The interfaces for a resource in REST must be generic. In other words, two resources must be accessible to client using the same methods (GET, POST, PUT, DELETE etc.).
- All the resources must be named using URI.
- The resources can be interconnected using URI through which the client can move from particular representation of one resource to another representation of a different resource.
- It supports layered components such as proxies, gateways etc. so as to implement security, increase efficiency etc.
The next natural question that you will be having is how REST differs from SOAP based services. We will be tackling that in next section.
REST and SOAP based services – the differences
There is vast amount of difference between SOAP based services and REST. The major differences can be described using the following points:
- Transport Protocol
- Based on RPC
- Persistence of state
- Uniform resource
The main points that make REST and SOAP different are the second and fourth points. Following are the details.
- Transport Protocol: REST is dependent on one transport protocol which is HTTP. SOAP based services can be used with variety of transport protocols.
- Based on RPC: REST is not based on RPC. Due to this REST can make use of generic interfaces. SOAP itself is RPC based. So each service will have its own methods and interfaces. This results in making the interfaces generic enough so that toolkits and clients around the services a tough undertaking.
- Standards: REST uses the existing web standards. It does not have its own standards. This helps in creating services easier as a different set library and toolkit is not required. SOAP based services has their own standards including but WSDL, SOAP, UDDI etc. So to create a service using SOAP you will require a minimum set of libraries to parse WSDL, understand SOAP and register itself with UDDI.
- Persistence of state: REST is stateless. Server does not keep track of change in state. So no handling will be available at server side. SOAP based services can handle sessions.
- Uniform resource: In REST access to each resource and methods to access the operations supported by it must be a uniform across all resources. For example, each resource is addressable using a URI. There is no intermediary that maps the resource to URI. In SOAP based services, uniformity of access to the resources and methods to the operations supported by the resource can vary from resource to resource.
The points described above are not to tell you which of them are better, rather to bring out the differences between the two types of web services that are currently most common. With that let us move to next section which will introduce you to RESTEasy.
RESTEasy – What is it?
In Java, all the frameworks that provide functionality to implement REST based applications are implementations of JAX-RS specification. RESTEasy is no exception. It is a portable implementation of JAX-RS. There are two versions of this specification – 1.1 and 2.0. All the RESTEasy versions prior to 3.x implemented JAX-RS 1.1. From 3.0 onwards RESTEasy has implemented JAX-RS 2.0.
The main features provided by RESTEasy are:
It can be used in any application server that runs on JDK 6 or higher. For example, RESTEasy based application/web service built for JBoss AS can be deployed in Glassfish.
RESTEasy has client framework. It leverages JAX-RS annotations using that a developer can write HTTP clients easily. One thing to keep in mind is that JAX-RS only defines annotations for server implementation only.
It supports caching semantics that includes cache revalidation. This ‘client cache’ is browser like cache that can be used by applications making use of RESTEasy client framework.
RESTEasy provides server side cache that is in-memory cache and caches the generated responses. It is local response cache since it sits in front of the REST service. And due to this RESTEasy can automatically handle ETag generation and cache revalidation.
Providers for common media types:
The most common media types used for data transfer in REST services are: XML, JSON, YAML, Multipart and Atom. RESTEasy has providers that marshall to and unmarshall from these media types.
Interceptors provide way to process requests and response before the request is passed to the business method or response is returned to the client. RESTEasy provides interceptors that can be used to either work on the body of request and response or on the request and response themselves.
In the coming chapters I will be focusing on how to use the above mentioned features and when to use them. Till then…