What are RESTful Web Services?

RESTful web services are services that are built to work best on the web. Representational State Transfer (REST) is an architectural style that specifies constraints, such as the uniform interface, that if applied to a web service induce desirable properties, such as performance, scalability, and modifiability, that enable services to work best on the Web. In the REST architectural style, 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 architectural style constrains an architecture to a client-server architecture, and is designed to use a stateless communication protocol, typically HTTP. In the REST architecture style, clients and servers exchange representations of resources using a standardized interface and protocol. These principles encourages RESTful applications to be simple, lightweight, and have high performance.

A paper that expands on the basic principles of REST technology can be found at http://www2008.org/papers/pdf/p805-pautassoA.pdf.

• Resource identification through URI. A RESTful Web service exposes a set of resources which identify the targets of the interaction with its clients. Resources are identified by URIs, which provide a global addressing space for resource and service discovery. This topic is discussed in The @Path Annotation and URI Path Templates.

• Uniform interface. Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT, GET, POST, and DELETE. PUT creates a new resource, which can be then deleted using DELETE. GET retrieves the current state of a resource in some representation. POST transfers a new state onto a resource. This topic is discussed in Responding to HTTP Resources.

• Self-descriptive messages. Resources are decoupled from their representation so that their content can be accessed in a variety of formats (such as HTML, XML, plain text, PDF, JPEG, JSON, and others). Metadata about the resource is available and used, for example, to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control. This topic is discussed in Responding to HTTP Resources and Using Entity Providers to Map HTTP Response and Request Entity Bodies.

• Stateful interactions through hyperlinks. Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, such as URI rewriting, cookies, and hidden form fields. State can be embedded in response messages to point to valid future states of the interaction. This topic is discussed somewhat in Using Entity Providers to Map HTTP Response and Request Entity Bodies, is discussed somewhat in the section Building URIs in the JAX-RS Overview document, and may be discussed in more detail in a forthcoming advanced version of this tutorial.

Where Does Jersey Fit In?

Jersey is Sun's production quality reference implementation for JSR 311: JAX-RS: The Java API for RESTful Web Services. Jersey implements support for the annotations defined in JSR-311, making it easy for developers to build RESTful web services with Java and the Java JVM. Jersey also adds additional features not specified by the JSR.

The latest version of the JAX-RS API's can be viewed at https://jsr311.dev.java.net/nonav/javadoc/index.html

If you are developing with Enterprise Server v3, you can install the Jersey samples and documentation using the Update Tool. Instructions for using the Update Tool can be found in the section Java EE 6 Tutorial Component.