With the prominence of the Internet and the ubiquity of HTTP in today's world, web services have become the main means for web-based systems to interoperate with each other. A web service is an interface that provides access to a web-facing system for clients and other services to consume.
Simple Object Access Protocol (SOAP) used to be the de facto choice for building such services. SOAP is an XML-based communication protocol, leveraging open standards. However, in recent years Representational State Transfer (REST) has become a very popular alternative to traditional SOAP web services. So, let's take a look at the principles behind REST. This chapter will cover the following topics:
Discussions of the REST principles
How the Spring Framework can help in the building of RESTful web services
A sample RESTful web service that will provide the backdrop for the rest of this book
REST is a software architecture approach for creating scalable web services. The term REST was coined by Roy Fielding in his PhD dissertation, and revolves around a number of principles. These principles underpin the architecture of RESTful web services and are described in the following sections.
At the core of REST are resources, and resources are identified using Uniform Resource Identifiers (URIs). Conceptually, resources are separate from their representation (that is, the format in which they are provided to clients). REST does not mandate any specific format, but typically includes XML and JSON (which will be discussed in Chapter 4, Data Representation).
Another distinctive property of REST is that clients interact entirely through hypermedia, which is dynamically provided by the application servers. Apart from endpoints, clients need no prior knowledge of how to interact with a RESTful service. This constraint is referred to as Hypermedia as the Engine of Application State (HATEOAS).
The client-server model that REST embraces enables the separation of client concerns, such as user interaction or user state management, from that of server concerns such as data storage and scalability.
This decoupling ensures that, provided an interface that is agreed upon, the development of client and server can be done independently. It also helps reduce complexity and improve the effectiveness of performance tuning.
REST advocates statelessness. No client state is stored on the server. All the information needed to perform operations is contained in the requests (as part of the URL, request body, or as HTTP headers).
This principle has significant advantages for scalability. Caching techniques will be discussed in Chapter 6, Performance.
Since REST typically leverages HTTP, it inherits all the caching properties that HTTP offers.
Given the style of communication between clients and servers, clients are not aware of which specific server they are interacting with. This property allows the introduction of intermediate servers that can, for example, handle security or offer load-balancing capabilities. These architectural concepts are discussed in more detail in Chapter 10, Scaling a RESTful Web Service.
For a service to be considered RESTful, it should abide by the preceding principles.
It is assumed that the reader is familiar with the Spring Framework (referred to as Spring from here on). We will therefore focus on the specificities of building RESTful web services with Spring, in this section.
Since REST hinges on URIs, the Spring Web MVC framework provides all the necessary tools for building RESTful endpoints. Annotations, such as
org.springframework.web.bind.annotation.RequestParam for mapping URLs and parameters form the basis for creating such endpoints. Chapter 3, The First Endpoint, will discuss these annotations and offer code samples to illustrate their use.
Reference documentation about the Spring Web MVC can be found at http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html.
With the technological context laid out, let's now look at one such RESTful service. Throughout this book, we will be building a sample web service that helps manage hotels and B&Bs.
One common piece of software in use in the hospitality industry is a property management system (careful readers will notice the unfortunate acronym for these systems). It allows automating the operations of hotels and B&Bs. For the purpose of this book, we will build such a system using Spring. Each component of this system will expose a RESTful API that will be consumed by a simple web interface.
Designing effective Application Programming Interfaces is a topic that deserves its own treaty. It is beyond the scope of this book to discuss these concerns in detail. The main characteristics that one should bear in mind when designing APIs are: ease of use, consistency, exposing as little as necessary, extensibility, and forward compatibility.
We will not delve into the specificities of Hibernate ORM in this book. However, documentation is available on Hibernate.org at http://hibernate.org/orm/.
In addition, for the purpose of simplifying the development and testing of our web service, we will use an embedded H2 database.
Documentation about H2 can be found at http://www.h2database.com.
Hibernate supports H2 out of the box, so no specific setup is required to use it as our embedded database.