LibraryLink ToToggle FramesPrintFeedback
Prev   Next

Chapter 1. Introduction to RESTful Services

Representational State Transfer (REST)is a software architecture style that centers around the transmission of data over HTTP, using only the four basic HTTP verbs. It also eschews the use of any additional wrappers such as a SOAP envelope and the use of any state data.

Overview

Representational State Transfer (REST) is an architectural style first described in a doctoral dissertation by a researcher named Roy Fielding. In REST, servers expose resources using a URI, and clients access these resources using the four HTTP verbs. As clients receive representations of a resource they are placed in a state. When they access a new resource, typically by following a link, they change, or transition, their state. In order to work, REST assumes that resources are capable of being represented using a pervasive standard grammar.

The World Wide Web is the most ubiquitous example of a system designed on REST principles. Web browsers act as clients accessing resources hosted on Web servers. The resources are represented using HTML or XML grammars that all Web browsers can consume. The browsers can also easily follow the links to new resources.

The advantages of REST style systems is that they are highly scalable and highly flexible. Because the resources are accessed and manipulated using the four HTTP verbs, the resources are exposed using a URI, and the resources are represented using standard grammars, clients are not as affected by changes to the servers. Also, REST style systems can take full advantage of the scalability features of HTTP such as caching and proxies.

Basic REST principles

RESTful architectures adhere to the following basic principles:

Resources

Resources are central to REST. A resource is a source of information that can be addressed using a URI. In the early days of the Web, resources were largely static documents. In the modern Web, a resource can be any source of information. For example a Web service can be a resource if it can be accessed using a URI.

RESTful endpoints exchange representations of the resources they address. A representation is a document containing the data provided by the resource. For example, the method of a Web service that provides access to a customer record wourld be a resource, the copy of the customer record exchanged between the service and the consumer is a representation of the resource.

REST best practices

When designing RESTful services it is helpful to keep in mind the following:

Wrapped mode vs. unwrapped mode

RESTful services can only send or receive one XML element. To enable the mapping of methods that use more than one parameter, FUSE Services Framework can use wrapped mode. In wrapped mode, FUSE Services Framework wraps the parameters with a root element derived from the operation name. For example, the operation Car findCar(String make, String model) could not be mapped to an XML POST request like the one shown in Example 1.1, “Invalid REST Request”.

Example 1.1. Invalid REST Request

<name>Dodge</name>
<model>Daytona</company>

Example 1.1, “Invalid REST Request” is invalid because it has two root XML elements, which is not allowed. Instead, the parameters would have to be wrapped with the operation name to make the POST valid. The resulting request is shown in Example 1.2, “Wrapped REST Request”.

Example 1.2. Wrapped REST Request

<findCar>
  <make>Dodge</make>
  <model>Daytona</model>
</findCar>

By default, FUSE Services Framework uses unwrapped mode, because, for cases where operations use a single parameter, it creates prettier XML. Using unwrapped mode, however, requires that you constrain your service interfaces to sending and receiving single elements. If your operation needs to take multiple parameters, you must combine them in an object. With the findCar() example above, you would want to create a FindCar class that holds the make and model data.

Implementing REST with FUSE Services Framework

FUSE Services Framework uses an HTTP binding to map Java interfaces into RESTful services. There are two ways to map the methods of the Java interface into resources:

Prev   Next
 Home