Chapter 42. Introduction to RESTful Web Services
Abstract
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 RESTful systems, 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 RESTful 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 URIs, and the resources are represented using standard grammars, clients are not as affected by changes to the servers. Also, RESTful 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:
- Application state and functionality are divided into resources.
- Resources are addressable using standard URIs that can be used as hypermedia links.
- All resources use only the four HTTP verbs.
DELETEGETPOSTPUT
- All resources provide information using the MIME types supported by HTTP.
- The protocol is stateless.
- Responses are cacheable.
- The protocol is layered.
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 would 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 Web services it is helpful to keep in mind the following:
- Provide a distinct URI for each resource you wish to expose.For example, if you are building a system that deals with driving records, each record should have a unique URI. If the system also provides information on parking violations and speeding fines, each type of resource should also have a unique base. For example, speeding fines could be accessed through /speedingfines/driverID and parking violations could be accessed through /parkingfines/driverID.
- Use nouns in your URIs.Using nouns highlights the fact that resources are things and not actions. URIs such as /ordering imply an action, whereas /orders implies a thing.
- Methods that map to
GETshould not change any data. - Use links in your responses.Putting links to other resources in your responses makes it easier for clients to follow a chain of data. For example, if your service returns a collection of resources, it would be easier for a client to access each of the individual resources using the provided links. If links are not included, a client needs to have additional logic to follow the chain to a specific node.
- Make your service stateless.Requiring the client or the service to maintain state information forces a tight coupling between the two. Tight couplings make upgrading and migrating more difficult. Maintaining state can also make recovery from communication errors more difficult.
Designing a RESTful Web Service
Regardless of the framework you use to implement a RESTful Web service, there are a number of steps that should be followed:
- Define the resources the service will expose.In general, a service will expose one or more resources that are organized as a tree. For example, a driving record service could be organized into three resources:
- /license/driverID
- /license/driverID/speedingfines
- /license/driverID/parkingfines
- Define what actions you want to be able to perform on each resource.For example, you may want to be able to update a diver's address or remove a parking ticket from a driver's record.
- Map the actions to the appropriate HTTP verbs.
Once you have defined the service, you can implement it using Apache CXF.
Implementing REST with Apache CXF
Apache CXF provides an implementation of the Java API for RESTFul Web Services(JAX-RS). JAX-RS provides a standardized way to map POJOs to resources using annotations.
When moving from the abstract service definition to a RESTful Web service implemented using JAX-RS, you need to do the following:
- Create a root resource class for the resource that represents the top of the service's resource tree.
- Map the service's other resources into sub-resources.
- Create methods to implement each of the HTTP verbs used by each of the resources.
Note
Apache CXF continues to support the old HTTP binding to map Java interfaces into RESTful Web services. The HTTP binding provides basic functionality and has a number of limitations. Developers are encouraged to update their applications to use JAX-RS.
Data bindings
By default, Apache CXF uses Java Architecture for XML Binding (JAXB) objects to map the resources and their representations to Java objects. Provides clean, well defined mappings between Java objects and XML elements.
The Apache CXF JAX-RS implementation also supports exchanging data using JavaScript Object Notation (JSON). JSON is a popular data format used by Ajax developers. The marshaling of data between JSON and JAXB is handled by the Apache CXF runtime.
