O'Reilly logo

RESTful Java with JAX-RS by Bill Burke

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Chapter 1. Introduction to REST

For those of us with computers, the World Wide Web is an intricate part of our lives. We use it to read the newspaper in the morning, pay our bills, perform stock trades, and buy goods and services, all through the browser, all over the network. “Googling” has become a part of our daily vocabulary as we use search engines to do research for school, find what time a movie is playing, or to just search for information on old friends. Door-to-door encyclopedia salesmen have gone the way of the dinosaur as Wikipedia has become the summarized source of human knowledge. People even socialize over the network using sites like Facebook and MySpace. Professional social networks are sprouting up in all industries as doctors, lawyers and all sorts of professionals use them to collaborate. As programmers, the Web is an intricate part of our daily jobs. We search for and download open source libraries to help us develop applications and frameworks for our companies. We build web-enabled applications so that anybody on the Internet or intranet can use a browser to interact with our systems.

Really, most of us take the Web for granted. Have you, as a programmer, sat down and tried to understand why the Web has been so successful? How has it grown from a simple network of researchers and academics to an interconnected worldwide community? What properties of the Web make it so viral?

One man, Roy Fielding, did ask these questions in his doctoral thesis, “Architectural Styles and the Design of Network-based Software Architectures.”[1] In it, he identifies specific architectural principles that answer the following questions:

  • Why is the Web so prevalent and ubiquitous?

  • What makes the Web scale?

  • How can I apply the architecture of the Web to my own applications?

The set of these architectural principles is called REpresentational State Transfer (REST) and are defined as:

Addressable resources

The key abstraction of information and data in REST is a resource, and each resource must be addressable via a URI (Uniform Resource Identifier).

A uniform, constrained interface

Use a small set of well-defined methods to manipulate your resources.


You interact with services using representations of that service. A resource referenced by one URI can have different formats. Different platforms need different formats. For example, browsers need HTML, JavaScript needs JSON (JavaScript Object Notation), and a Java application may need XML.

Communicate statelessly

Stateless applications are easier to scale.

Hypermedia As The Engine Of Application State (HATEOAS)

Let your data formats drive state transitions in your applications.

For a PhD thesis, Roy’s paper is actually very readable and, thankfully, not very long. It, along with Leonard Richardson and Sam Ruby’s book RESTful Web Services (O’Reilly), is an excellent reference for understanding REST. I will give a much briefer introduction to REST and the Internet protocol it uses (HTTP) within this chapter.

REST and the Rebirth of HTTP

REST isn’t protocol-specific, but when people talk about REST, they usually mean REST over HTTP. Learning about REST was as much of a rediscovery and reappreciation of the HTTP protocol for me as learning a new style of distributed application development. Browser-based web applications see only a tiny fraction of the features of HTTP. Non-RESTful technologies like SOAP and WS-* use HTTP strictly as a transport protocol and thus use a very small subset of its capabilities. Many would say that SOAP and WS-* use HTTP solely to tunnel through firewalls. HTTP is actually a very rich application protocol that provides a multitude of interesting and useful capabilities for application developers. You will need a good understanding of HTTP in order to write RESTful web services.

HTTP is a synchronous request/response-based application network protocol used for distributed, collaborative, document-based systems. It is the primary protocol used on the Web, in particular, by browsers such as Firefox, MS Internet Explorer, Safari, and Netscape. The protocol is very simple: the client sends a request message made up of the HTTP method being invoked, the location of the resource you are interested in invoking, a variable set of headers, and an optional message body that can basically be anything you want, including HTML, plain text, XML, JSON, even binary data. Here’s an example:

GET /resteasy/index.html HTTP/1.1
Host: jboss.org
User-Agent: Mozilla/5.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language:      en-us,en;q=0.5
Accept-Encoding:     gzip,deflate

Your browser would send this request if you wanted to look at http://jboss.org/resteasy/index.html. GET is the method we are invoking on the server. /resteasy/index.html is the object we are interested in. HTTP/1.1 is the version of the protocol. Host, User-Agent, Accept, Accept-Language, and Accept-Encoding are all message headers. There is no request body, as we are querying information from the server.

The response message from the server is very similar. It contains the version of HTTP we are using, a response code, a short message that explains the response code, a variable set of optional headers, and an optional message body. Here’s the message the server might respond with using the previous GET query:

HTTP/1.1 200 OK
X-Powered-By: Servlet 2.4; JBoss-4.2.2.GA
Content-Type: text/html

<title>JBoss RESTEasy Project</title>
<h1>JBoss RESTEasy</h1>
<p>JBoss RESTEasy is an open source implementation of the JAX-RS specification...

The response code of this message is 200, and the status message is “OK.” This code means that the request was processed successfully and that the client is receiving the information it requested. HTTP has a large set of response codes. They can be informational codes like 200, “OK,” or error codes like 500, “Internal Server Error.” Visit www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for a more complete and verbose listing of these codes.

This response message also has a message body that is a chunk of HTML. We know it is HTML by the Content-Type header.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required