RESTful Web Services

Chapter 6

This chapter describes the REST architecture and RESTful web services, and explains how to use the REST API to create RESTful web services.

What Are RESTful Web Services?

Representational State Transfer (REST) is a software application architecture modeled after the way data is represented, accessed, and modified on the web. In the REST architecture, data and functionality are considered resources, and these resources are accessed using Uniform Resource Identifiers (URIs), typically links on the web. The resources are acted upon by using a set of simple, well-defined operations. The REST architecture is fundamentally a client-server architecture, and is designed to use a stateless communication protocol, typically HTTP. In the REST architecture, clients and servers exchange representations of resources using a standardized interface and protocol. These principles encourages REST applications to be simple, lightweight, and have high performance.

RESTful web services are web applications built upon the REST architecture. They:

expose resources (data and functionality) through web URIs
use the four main HTTP methods to create, retrieve, update, and delete resources

RESTful web services typically map the four main HTTP methods to the so-called CRUD actions: create, retrieve, update, and delete. The following table shows a mapping of HTTP methods to these CRUD actions.

Table 6-1 HTTP Methods and their Corresponding CRUD Action

HTTP Method	CRUD Action
`GET`	Retrieve a resource.
`POST`	Create a resource.
`PUT`	Update a resource.
`DELETE`	Delete a resource.

RESTful Web Services and Other Styles of Web Services

REST web services share many characteristics with other styles of web services like remote procedure call (RPC) and document-based web services that use SOAP as the underlying protocol, but also differ in several important ways. RPC and document-based web services, like REST web services, are designed to be lightweight, accessible via URIs, and typically use HTTP as the underlying protocol. REST and SOAP-based web services are also platform and programming language independent, and in both architectures clients and servers are loosely coupled. That is, clients and servers interact with a limited set of assumptions about each other.

REST web services were developed largely as an alternative to some of the perceived drawbacks of SOAP-based web services. The SOAP protocol was designed as a way to make remote procedure calls via HTTP, using XML as the underlying data format, and using standard XML types. Eventually the RPC aspects of SOAP web services were augmented with a document-based architecture, where clients and servers exchange XML documents to enact some change in the client or server applications. As the use of SOAP web services evolved, the architecture was expanded to deal with more complicated application functionality, like security and message reliability. As a result, developing SOAP web services and clients has become more complicated.

REST web services aim to be simple, and this is accomplished by limiting the types of operations one can perform on a resource.

Developing RESTful Web Services with the REST API

The API for developing RESTful web services is a Java programming language API designed to make it easy to develop applications that use the REST architecture.

The API uses Java programming language annotations to simplify the development of RESTful web services. Developers decorate Java programming language class files with REST-specific annotations to define resources and the actions that can be performed on those resources. The annotation processing tool apt is then run on the class to generate helper classes and artifacts for the resource, and the collection of classes and artifacts is then built into a web application archive (WAR). The resources are exposed to clients by deploying the WAR to a Java EE server.

URI Templates

URI Templates are URIs with variables embedded within the URI syntax. These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI. Variables are denoted by curly braces. For example, look at the following URI Template:

http://example.com/users/{username}

A RESTful web service configured to respond to requests to this URI Template will respond to all of the following URIs:

http://example.com/users/jgatsby
http://example.com/users/ncarraway
http://example.com/users/dbuchanan

URI Template Variables

A URI Template has one or more variables, with each variable name surrounded by curly braces, { to begin the variable name and } to end it. In the example above, username is the variable name, and at runtime a resource configured to respond to the above URI Template will attempt to process the URI data that corresponds to the location of {username} in the URI as the variable data for username.

A variable name can be used more than once in the URI Template.

If a character in the value of a variable would conflict with the reserved characters of a URI, the conflicting character should be substituted with percent encoding. For example, spaces in the value of a variable should be substituted with %20.

Be careful when defining URI Templates that the resulting URI after substitution is valid.

Examples of URI Template Variables

The following table lists some examples of URI Template variables and how the URIs are resolved after substitution. The following variable names and values are used in the examples:

name1: jay
name2: gatsby
name3:
location: East%20Egg
queryString: query=The+Great+Gatsby
question: why

Note - The value of the name3 variable is an empty string.

Table 6-2 Examples of URI Templates

URI Template	URI After Substitution
`http://example.com/{name1}/{name2}/`	`http://example.com/jay/gatsby/`
`http://example.com/{name1}{name2}/`	`http://example.com/jaygatsby/`
`http://example.com/{question}/{question}/{question}/`	`http://example.com/why/why/why/`
`http://example.com/maps/{location}`	`http://example.com/maps/East%20Egg`
`http://example.com/search?{queryString}`	`http://example.com/search?query=The+Great+Gatsby`
`http://example.com/{name3}/home/`	`http://example.com//home/`

The `UriTemplate` Annotation

The com.sun.ws.rest.api.UriTemplate annotation defines the URI Template to which the resource responds, and is specified at the class level of a resource. The @UriTemplate annotation's value is a partial URI Template relative to the base URI of the server on which the resource is deployed, the context root of the WAR, and the URL pattern that the REST API helper servlet responds.

For example, if you want to deploy a resource that responds to the URI Template http://example.com/myContextRoot/restbeans/{name1}/{name2}/, you must deploy the WAR to a Java EE server that responds to requests to the http://example.com/myContextRoot URI, and then decorate your resource with the following @UriTemplate annotation:

@UriTemplate("/{name1}/{name2}/")
public class SomeResource {
	...
}

In this example, the URL pattern for the REST API helper servlet, specified in web.xml, is the default:

<servlet-mapping>
	<servlet-name>My RESTBean Resource</servlet-name>
	<url-pattern>/restbeans/*</url-pattern>
</servlet-mapping>

Responding to HTTP Requests

The behavior of a resource is determined by which of the HTTP methods (typically, GET, POST, PUT, DELETE) the resource is responding to.

The `HttpMethod` Annotation

Within a resource class file, HTTP methods are mapped to Java programming language methods using the com.sun.ws.rest.api.HttpMethod annotation.

For example, the following resource defines a single method that responds to HTTP GET requests:

@UriTemplate("/hello")
public class Hello {
	...
	@HttpMethod("GET")
	public String sayHello() {
		...
	}
}

Methods decorated with @HttpMethod must return void, a Java programming language type, a Representation<?> object, or a com.sun.ws.rest.api.HttpResponse object. They may have a single, optional parameter of type Representation<?>, which allows you to access the contents of the HTTP request body, or multiple parameters may be extracted from the URI using the UriParam or QueryParam annotations as described in Extracting Method Parameters From URIs. Only one method parameter of type Representation<?> is allowed. The HTTP PUT and POST methods expect an HTTP request body, so you should use an input parameter of type Representation<?> for methods that respond to PUT and POST requests. See Using Entities and Representations for more information on using Representation<?> types.

If you do not specify the HTTP method as an element of @HttpMethod, the annotated method must begin with the lowercase name of one of the HTTP method constants (GET, POST, PUT, DELETE). For example, the following method declaration:

@HttpMethod
public String getName() {...}

is equivalent to this method declaration:

@HttpMethod("GET")
public String getName() {...)

Allowed HTTP Methods in `@HttpMethod`

The following table lists the HTTP methods allowed as element in the @HttpMethod annotation.

Table 6-3 HTTP Methods

HTTP Method	Use
`GET`	retrieve or display a resource
`POST`	create or modify a resource
`PUT`	update or modify a resource
`DELETE`	delete a resource
`HEAD`	responds like the `GET` method, but without a response body; for retrieving metadata on the resource

This tutorial will only discuss the four main HTTP method: GET, POST, PUT, and DELETE.