O'Reilly logo

Java Web Services: Up and Running by Martin Kalin

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 4. RESTful Web Services

What Is REST?

Roy Fielding (http://roy.gbiv.com) coined the acronym REST in his Ph.D. dissertation. Chapter 5 of his dissertation lays out the guiding principles for what have come to be known as REST-style or RESTful web services. Fielding has an impressive resume. He is, among other things, a principal author of the HTTP specification and a cofounder of the Apache Software Foundation.

REST and SOAP are quite different. SOAP is a messaging protocol, whereas REST is a style of software architecture for distributed hypermedia systems; that is, systems in which text, graphics, audio, and other media are stored across a network and interconnected through hyperlinks. The World Wide Web is the obvious example of such a system. As our focus is web services, the World Wide Web is the distributed hypermedia system of interest. In the Web, HTTP is both a transport protocol and a messaging system because HTTP requests and responses are messages. The payloads of HTTP messages can be typed using the MIME type system, and HTTP provides response status codes to inform the requester about whether a request succeeded and, if not, why.

REST stands for REpresentation State Transfer, which requires clarification because the central abstraction in REST—the resource—does not occur in the acronym. A resource in the RESTful sense is anything that has an URI; that is, an identifier that satisfies formatting requirements. The formatting requirements are what make URIs uniform. Recall, too, that URI stands for Uniform Resource Identifier; hence, the notions of URI and resource are intertwined.

In practice, a resource is an informational item that has hyperlinks to it. Hyperlinks use URIs to do the linking. Examples of resources are plentiful but likewise misleading in suggesting that resources must have something in common other than identifiability through URIs. The gross national product of Lithuania in 2001 is a resource, as is the Modern Jazz Quartet. Ernie Bank’s baseball accomplishments count as a resource, as does the maximum flow algorithm. The concept of a resource is remarkably broad but, at the same time, impressively simple and precise.

As Web-based informational items, resources are pointless unless they have at least one representation. In the Web, representations are MIME-typed. The most common type of resource representation is probably still text/html, but nowadays resources tend to have multiple representations. For example, there are various interlinked HTML pages that represent the Modern Jazz Quartet, but there are also audio and audiovisual representations of this resource.

Resources have state. For example, Ernie Bank’s baseball accomplishments changed during his career with the Chicago Cubs from 1953 through 1971 and culminated in his 1977 induction into the Baseball Hall of Fame. A useful representation must capture a resource’s state. For example, the current HTML pages on Ernie at the Baseball Reference website need to represent all of his major league accomplishments, from his rookie year in 1953 through his induction into the Hall of Fame.

In a RESTful request targeted at a resource, the resource itself remains on the service machine. The requester typically receives a representation of the resource if the request succeeds. It is the representation that transfers from the service machine to the requester machine. In different terms, a RESTful client issues a request that involves a resource, for instance, a request to read the resource. If this read request succeeds, a typed representation (for instance, text/html) of the resource is transferred from the server that hosts the resource to the client that issued the request. The representation is a good one only if it captures the resource’s state in some appropriate way.

In summary, RESTful web services require not just resources to represent but also client-invoked operations on such resources. At the core of the RESTful approach is the insight that HTTP, despite the occurrence of Transport in its name, is an API and not simply a transport protocol. HTTP has its well-known verbs, officially known as methods. Table 4-1 shows the HTTP verbs that correspond to the CRUD (Create, Read, Update, Delete) operations so familiar throughout computing.

Table 4-1. HTTP verbs and CRUD operations

HTTP verbMeaning in CRUD terms
POSTCreate a new resource from the request data
GETRead a resource
PUTUpdate a resource from the request data
DELETEDelete a resource

Although HTTP is not case-sensitive, the HTTP verbs are traditionally written in uppercase. There are additional verbs. For example, the verb HEAD is a variation on GET that requests only the HTTP headers that would be sent to fulfill a GET request. There are also TRACE and INFO verbs.

Figure 4-1 is a whimsical depiction of a resource with its identifying URI, together with a RESTful client and some typed representations sent as responses to HTTP requests for the resource. Each HTTP request includes a verb to indicate which CRUD operation should be performed on the resource. A good representation is precisely one that matches the requested operation and captures the resource’s state in some appropriate way. For example, in this depiction a GET request could return my biography as a hacker as either an HTML document or a short video summary. The video would fail to capture the state of the resource if it depicted, say, only the major disasters in my brother’s career rather than those in my own. A typical HTML representation of the resource would include hyperlinks to other resources, which in turn could be the target of HTTP requests with the appropriate CRUD verbs.

A small slice of a RESTful system

Figure 4-1. A small slice of a RESTful system

HTTP also has standard response codes, such as 404 to signal that the requested resource could not be found, and 200 to signal that the request was handled successfully. In short, HTTP provides request verbs and MIME types for client requests and status codes (and MIME types) for service responses.

Modern browsers generate only GET and POST requests. Moreover, many applications treat these two types of requests interchangeably. For example, Java HttpServlets have callback methods such as doGet and doPost that handle GET and POST requests, respectively. Each callback has the same parameter types, HttpServletRequest (the key/value pairs from the requester) and HttpServletResponse (a typed response to the requester). It is common to have the two callbacks execute the same code (for instance, by having one invoke the other), thereby conflating the original HTTP distinction between read and create. A key guiding principle of the RESTful style is to respect the original meanings of the HTTP verbs. In particular, any GET request should be side effect-free (or, in jargon, idempotent) because a GET is a read rather than a create, update, or delete operation. A GET as a read with no side effects is called a safe GET.

The REST approach does not imply that either resources or the processing needed to generate adequate representations of them are simple. A REST-style web service might be every bit as subtle and complicated as a SOAP-based service. The RESTful approach tries to simplify matters by taking what HTTP, with its MIME type system, already offers: built-in CRUD operations, uniformly identifiable resources, and typed representations that can capture a resource’s state. REST as a design philosophy tries to isolate application complexity at the endpoints, that is, at the client and at the service. A service may require lots of logic and computation to maintain resources and to generate adequate representation of resources—for instance, large and subtly formatted XML documents—and a client may require significant XML processing to extract the desired information from the XML representations transferred from the service to the client. Yet the RESTful approach keeps the complexity out of the transport level, as a resource representation is transferred to the client as the body of an HTTP response message. By contrast, a SOAP-based service inevitably complicates the transport level because a SOAP message is encapsulated as the body of a transport message; for instance, an HTTP or SMTP message. SOAP requires messages within messages, whereas REST does not.[1]

Verbs and Opaque Nouns

A URI is meant to be opaque, which means that the URI:


has no inherent connection to the URI:


although Fred happens to be a citizen of Bedrock. These are simply two different, independent identifiers. Of course, a good URI designer will come up with URIs that are suggestive about what they are meant to identify. The point is that URIs have no intrinsic hierarchical structure. URIs can and should be interpreted, but these interpretations are imposed on URIs, not inherent in them. Although URI syntax looks like the syntax used to navigate a hierarchical file system, this resemblance is misleading. A URI is an opaque identifier, a logically proper name that denotes exactly one resource.

In RESTful services, then, URIs act as identifying nouns and HTTP methods act as verbs that specify operations on the resources identified by these nouns. For reference, here is the HTTP start line from a client’s request against the TimeServer service in Chapter 1:

POST HTTP/ 1.1      

The HTTP verb comes first, then the URI, and finally the requester’s version of HTTP. This URI is, of course, a URL that locates the web service. Table 4-2 uses simplified URIs to summarize the intended meanings of HTTP/URI combinations.

Table 4-2. Sample HTTP verb/URI pairs

HTTP verb/URIIntended CRUD meaning
POST empsCreate a new employee from the request data
GET empsRead a list of all employees
GET emps?id=27Read a singleton list of employee 27
PUT empsUpdate the employee list with the request data
DELETE empsDelete the employee list
DELETE emps?id=27Delete employee 27

These verb/URI pairs are terse, precise, and uniform in style. The pairs illustrate that RESTful conventions can yield simple, clear expressions about which operation should be performed on which resource. The POST and PUT verbs are used in requests that have an HTTP body; hence, the request data are housed in the HTTP message body. The GET and DELETE verbs are used in requests that have no body; hence, the request data are sent as query string entries.

For the record, RESTful web services are Turing complete; that is, these services are equal in power to any computational system, including a system that consists of SOAP-based web services. Yet the decision about whether to be RESTful in a particular application depends, as always, on practical matters. This first section has looked at REST from on high; it is now time to descend into details through examples.

[1] For a thorough coverage of REST-style web services, see Leonard Richardson and Sam Ruby’s book RESTful Web Services (O’Reilly).

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