REST - Representational State Transfer

1.1. Overview

REST is an architectural style which is based on web-standards and the HTTP protocol. REST was first described by Roy Fielding in 2000.

In a REST based architecture everything is a resource. A resource is accessed via a common interface based on the HTTP standard methods. In an REST architecture you typically have a REST server which provides access to the resources and a REST client which accesses and modify the REST resources. Every resource should support the HTTP common operations. Resources are identified by global ID's (which are typically URIs).

REST allows that resources have different representations, e.g. text, xml, json etc. The rest client can ask for specific representation via the HTTP protocol (Content Negotiation).

1.2. HTTP methods

The HTTP standards methods which are typical used in REST are PUT, GET, POST, DELETE.

• GET defines a reading access of the resource without side-effects. The resource is never changed via a GET request, e.g. the request has no side effects (idempotent).

• PUT creates a new resource, must also be idempotent.

• DELETE removes the resources. The operations are idempotent, they can get repeated without leading to different results.

• POST updates an existing resource or creates a new resource.

1.3. RESTFul webservices

A RESTFul webservices is based on the HTTP methods and the concept of REST. It typically defines the base URI for the services, the MIME-types its supports (XML, Text, JSON, user-defined,..) and the set of operations (POST, GET, PUT, DELETE) which are supported. JAX-RS supports the creation of XML and JSON via JAXB .

1.4. Java, REST and Jersey

Java defines standard REST support via JAX-RS (The Java API for RESTful Web Services) in JSR 311 .JAX-RS uses annotations to define the REST relevance of classes.

Via your "web.xml" you will register a servlet provided by Jersey and also define the path under which your REST web application will be available. The base URL of this servlet is:

				
http://your_domain:port/display-name/url-pattern/path_from_rest_class
			

This servlet which analyze the incoming HTTP request and select the correct class and method to respond to this request. This selection is based on annotation in the class and methods.

The most important annotations in JAX-RS are the following.

Table 1. Sample Table

Annotation	Description
@PATH(your_path)	Sets the path to base URL + /your_path. The base URL is based on your application name, the servlet and the URL pattern from the web.xml" configuration file.
@POST	Indicates that the following method will answer to a HTTP POST request
@GET	Indicates that the following method will answer to a HTTP GET request
@PUT	Indicates that the following method will answer to a HTTP PUT request
@DELETE	Indicates that the following method will answer to a HTTP DELETE request
@Produces( MediaType.TEXT_PLAIN [, more-types ] )	@Produces defines which MIME type is delivered by a method annotated with @GET. In the example text ("text/plain" ) is produced. Other examples would be "application/xml" or "application/json".
@Consumes( type [, more-types ] )	@Consumes defines which MIME type is consumed by this method.
@PathParam	Used to inject values from the URL into a method parameter. This way you inject for example the ID of a resource into the method to get the correct object.

The complete path to a resource is therefore based on the base URL and the @PATh annotation in your class.

				
http://your_domain:port/display-name/url-pattern/path_from_rest_class
			

Jersey is the reference implementation for this specification. Jersey contains basically a REST server and a REST client. The core client is mainly available for testing and provides a library to communicate with the server.

A REST web application consists out of data classes (resources) and services. These two types are typically maintained in different packages as the Jersey servlet will be instructed via the "web.xml"to scan certain packages for data classes.