In this chapter, we will cover the Representational State Transfer (REST) software architectural style, as described in Roy Fielding's PhD dissertation. You may find a brief discussion on HTTP before getting into the details of REST. Once the base is set, we will be ready for the next step. We will then discuss the set of constraints, the main components, and the abstractions that make a software system RESTful. Here is the list of topics covered in this chapter:

• The REST architectural style
• Introducing HTTP
• The evolution of RESTful web services
• The core architectural elements of a RESTful system
• The description and discovery of RESTful web services
• Java tools and frameworks for building RESTful web services

REST is not an architecture; rather, it is a set of constraints that creates a software architectural style, which can be used for building distributed applications. A major challenge to the distributed applications is attributed to the diversity of systems in an enterprise offering silos of business information, as depicted in the following diagram:

Often, an enterprise demands simplified access and updates to data residing in different systems. Fielding arrived at REST by evaluating all the networking resources and technologies available for creating distributed applications. He observed that without any constraints, one may end up developing applications with no rules or limits that are hard to maintain and extend. After considerable research on building a better architecture for a distributed application, he ended up with the following constraints that define a RESTful system:

• Client-server: This constraint keeps the client and server loosely coupled. In this case, the client does not need to know the implementation details in the server, and the server is not worried about how the data is used by the client. However, a common interface is maintained between the client and server to ease communication.
• Stateless: There should be no need for the service to keep user sessions. In other words, each request should be independent of the others. This improves scalability, as the server does not need to manage the state across multiple requests, with some trade-off on the network performance.
• Cacheable: This constraint has to support a caching system. The network infrastructure should support a cache at different levels. Caching can avoid repeated round trips between the client and the server for retrieving the same resource.
• Uniform interface: This constraint indicates a generic interface to manage all the interactions between the client and server in a unified way, which simplifies and decouples the architecture. This constraint indicates that each resource exposed for use by the client must have a unique address and should be accessible through a generic interface. The client can act on the resources by using a generic set of methods.
• Layered system: The server can have multiple layers for implementation. This layered architecture helps to improve scalability by enabling load balancing. It also improves the performance by providing shared caches at different levels. Being the door to the system, the top layer can enforce security policies as well.
• Code on demand: This constraint is optional. This constraint indicates that the functionality of the client applications can be extended at runtime by allowing a code download from the server and executing the code. Some examples are the applets and the JavaScript code that get transferred and executed at the client side at runtime.

The following diagram illustrates a high-level architectural view of a RESTful system:

The preceding constraints do not dictate what kind of technology to use; they only define how the data is transferred between components and the benefits of the guidelines. Therefore, a RESTful system can be implemented in any available networking architecture. More importantly, there is no need for us to invent new technologies or networking protocols. We can very well use the existing networking infrastructures, such as the World Wide Web (WWW), to create RESTful architectures. Consequently, a RESTful architecture is one that is maintainable, extendable, and distributed.

Before all the REST constraints were formalized, we already had a working example of a RESTful system—the web. Now, you may ask why introduce these RESTful requirements to web application development when it is agreed that the web is already RESTful.

Here is the answer, we first need to qualify what it means for the web to be RESTful. On one hand, the static web is RESTful because static websites follow Fielding's definition of a RESTful architecture. For instance, the existing web infrastructure provides caching systems, stateless connections, and unique hyperlinks to resources, where resources include all the documents available on every website, and the representation of these documents is already set by files being browser-readable (the HTML files, for example). Therefore, the static web is a system built in the REST-like architectural style. In simple words, we can say that REST leverages these amazing features of the web with some constraints.

On the other hand, traditional dynamic web applications have not always been RESTful because they typically break some of the outlined constraints. For instance, most dynamic applications are not stateless, as servers require tracking users through the container sessions or client-side cookie schemes. Therefore, we conclude that the dynamic web is not normally built in the REST-like architectural style.

Now, you may be curious to learn more about a RESTful system. The rest of the chapter will definitely help you to know the internals. However, the topics on the RESTful system that we are going to discuss in the coming sections may need some basic knowledge of HTTP. So, let's take a crash course on HTTP to learn some basics and then proceed with our discussions thereafter. You can skip the next section if you are already familiar with HTTP.

Hypertext Transfer Protocol (HTTP) is the foundation of data communication for WWW. To comprehend HTTP, it is essential to understand the etymology of hypertext. The major constraint of written text is its linearity, that is, not being able to easily reference other text that the user can easily access. Hypertext overcomes this constraint, with the concept of hyperlinks, which allows the user to easily navigate to the referenced section. HTTP is an application layer protocol that defines how hypertext messages are formatted, transmitted, and processed over the internet. Let's have a quick recap of HTTP in this section.

HTTP has been consistently evolving over time. So far, there have been three versions. HTTP/0.9 was the first documented version, which was released in the year 1991. This was very primitive and supported only the GET method. Later, HTTP/1.0 was released in the year 1996 with more features and corrections for the shortcomings of the previous release. HTTP/1.0 supported more request methods such as GET, HEAD, and POST. The next release was HTTP/1.1 in the year 1999. This was a revision of HTTP/1.0. This version is in common use today.

HTTP/2 (originally named HTTP 2.0) was published in 2015. It is mainly focused on how the data is framed and transported between the client and server. It is currently supported by major browsers and as of May 2017, 13.7% of the top 10 million websites support HTTP/2.

HTTP works in a request-response manner. Let's take an example to understand this model better.

The following example illustrates the basic request-response model of communication between a web browser and a server over HTTP. The following sequence diagram illustrates the request and response messages sent between the client and server:

Here is the detailed explanation for the sequence of actions shown in the preceding diagram.

The user enters http://www.example.com/index.html in the browser and then submits the request. The browser establishes a connection with the server and sends a request to the server in the form of a request method (URI) and a protocol version, followed by a message containing the request modifiers, client information, and possible body content. The sample request looks as follows:

GET /index.html HTTP/1.1 
Host: www.example.com 
User-Agent: Mozilla/5.0 
Accept: text/htmlAccept-Language: en-US,en;q=0.5 
Accept-Encoding: gzip, deflate 
Connection: keep-alive 

Let's take a minute to understand the structure of the preceding message. The following code is what you see in the first lines of request in our example:

GET /index.html HTTP/1.1 

The general format for the request line is an HTTP command, followed by the resource to retrieve and the HTTP version supported by the client. The client can be any application that understands HTTP, although this example refers to a web browser as the client. The request line and other header fields must end with a carriage return character followed by a line-feed character. In the preceding example, the browser instructs the server to get the index.html file through the HTTP 1.1 protocol.

The rest of the information that you may see in the request message is the HTTP header values for use by the server. The header fields are colon-separated key-value pairs in the plain-text format, terminated by a carriage return and followed by a line feed character. The header fields in the request, such as the acceptable content types, languages, and connection type, are the operating parameters for an HTTP transaction. The server can use this information while preparing the response to the request. A blank line is used at the end of the header to indicate the end of the header portion in a request.

The last part of an HTTP request is the HTTP body. Typically, the body is left blank unless the client has some data to submit to the server. In our example, the body part is empty as this is a GET request for retrieving a page from the server.

So far, we have been discussing the HTTP request sent by the client. Now, let's take a look at what happens on the server when the message is received. Once the server receives the HTTP request, it will process the message and return a response to the client. The response is made up of the reply status code from the server, followed by the HTTP header and a response content body:

HTTP/1.1 200 OK 
Accept-Ranges: bytes 
Cache-Control: max-age=604800 
Content-Type: text/html 
Date: Wed, 03 Dec 2014 15:05:59 GMT 
Content-Length: 1270 
 
<html> 
<head> 
  <title>An Example Page</title> 
</head> 
<body> 
  Hello World ! 
</body> 
</html>. 

The first line in the response is a status line. It contains the HTTP version that the server is using, followed by a numeric status code and its associated textual phrase. The status code indicates one of the following parameters: informational codes, success of the request, client error, server error, or redirection of the request. In our example, the status line is as follows:

HTTP/1.1 200 OK 

The next item in the response is the HTTP response header. Similar to the request header, the response header follows the colon-separated name-value pair format terminated by a carriage return and line feed characters. The HTTP response header can contain useful information about the resource being fetched, the server hosting the resource, and some parameters controlling the client behavior while dealing with resource, such as content type, cache expiry, and refresh rate.

The last part of the response is the response body. Upon successful processing of the request, the server will add the requested resource in the HTTP response body. It can be HTML, binary data, image, video, text, XML, JSON, and so on. Once the response body has been sent to the requestor, the HTTP server will disconnect if the connection created during the request is not of the keep-alive type (using the Connection: keep-alive header).

You may see the term Uniform Resource Identifier (URI) used very frequently in the rest of the chapter. A URI is a text that identifies any resource or name on the internet. One can further classify a URI as a Uniform Resource Locator (URL) if the text used for identifying the resource also holds the means for accessing the resource, such as HTTP or FTP. The following is one such example:

https://www.packtpub.com/application-development

In the previous session, we discussed about the HTTP GET request method for retrieving a page from the server. More request methods similar to GET are available with HTTP, each performing specific actions on the target resource. Let's learn about these methods and their role in client-server communication over HTTP.

The set of common methods for HTTP/1.1 is listed in the following table:

We may use some of these HTTP methods, such as GET, POST, PUT, and DELETE, while building RESTful web services in the later chapters.

Continuing our discussion on HTTP, the next section discusses the HTTP header parameter, which identifies the content type for the message body.

When we discussed the HTTP request-response model in the Understanding the HTTP request-response model section, we talked about the HTTP header parameters (the name-value pairs) that define the operating parameters of an HTTP transaction. In this section, we will cover the header parameter used for describing the content types present in the request and the response message body.

The Content-Type header in an HTTP request or response describes the content type for the message body. The Accept header in the request tells the server the content types that the client is expecting in the response body. The content types are represented using the internet media type. The internet media type (also known as the MIME type) indicates the type of data that a file contains. Here is an example:

Content-Type: text/html 

This header indicates that the body content is presented in the html format. The format of the content type values is a primary type/subtype followed by optional semicolon-delimited attribute-value pairs (known as parameters).

The internet media types are broadly classified into the following categories on the basis of the primary (or initial) Content-Type header:

• text: This type indicates that the content is a plain text and no special software is required to read the contents. The subtype represents more specific details about the content, which can be used by the client for special processing, if any. For instance, Content-Type: text/html indicates that the body content is html, and the client can use this hint to kick off an appropriate rendering engine while displaying the response.
• multipart: As the name indicates, this type consists of multiple parts of independent data types. For instance, Content-Type: multipart/form-data is used for submitting forms that contain the files, non-ASCII data, and binary data.
• message: This type encapsulates more messages. It allows messages to contain other messages or pointers to other messages. For instance, the Content-Type: message/partial content type allows for large messages to be broken up into smaller messages. The full message can then be read by the client (user agent) by putting all the broken messages together.
• image: This type represents the image data. For instance, Content-Type: image/png indicates that the body content is a .png image.
• audio: This type indicates the audio data. For instance, Content-Type: audio/mpeg indicates that the body content is MP3 or other MPEG audio.
• video: This type indicates the video data. For instance, Content-Type: video/mp4 indicates that the body content is an MP4 video.
• application: This type represents the application data or binary data. For instance, Content-Type: application/json; charset=utf-8 designates the content to be in the JavaScript Object Notation (JSON) format, encoded with UTF-8 character encoding.

We may need to use some of these content types in the next chapters while developing the RESTful web services. This hint will be used by the client to correctly process the response body.

The next topic, a simple but important one, is on HTTP status codes.

For every HTTP request, the server returns a status code indicating the processing status of the request. In this section, we will see some of the frequently used HTTP status codes. A basic understanding of status codes will definitely help us later while designing RESTful web services:

• 1xx Informational: This series of status codes indicates informational content. This means that the request is received and processing is going on. Here are the frequently used informational status codes:
  • 100 Continue: This code indicates that the server has received the request header and the client can now send the body content. In this case, the client first makes a request (with the Expect: 100-continue header) to check whether it can start with a partial request. The server can then respond either with 100 Continue (OK) or 417 Expectation Failed (No) along with an appropriate reason.
  • 101 Switching Protocols: This code indicates that the server is OK for a protocol switch request from the client.
  • 102 Processing: This code is an informational status code used for long running processing to prevent the client from timing out. This tells the client to wait for the future response, which will have the actual response body.
• 2xx Success: This series of status codes indicates the successful processing of requests. Some of the frequently used status codes in this class are as follows:
  • 200 OK: This code indicates that the request is successful and the response content is returned to the client as appropriate.
  • 201 Created: This code indicates that the request is successful and a new resource is created.
  • 204 No Content: This code indicates that the request is processed successfully, but there's no return value for this request. For instance, you may find such status codes in response to the deletion of a resource.
• 3xx Redirection: This series of status codes indicates that the client needs to perform further actions to logically end the request. A frequently used status code in this class is as follows:
  • 304 Not Modified: This status indicates that the resource has not been modified since it was last accessed. This code is returned only when allowed by the client via setting the request headers as If-Modified-Since or If-None-Match. The client can take appropriate action on the basis of this status code.
• 4xx Client Error: This series of status codes indicates an error in processing the request. Some of the frequently used status codes in this class are as follows:
  • 400 Bad Request: This code indicates that the server failed to process the request because of malformed syntax in the request. The client can try again after correcting the request.
  • 401 Unauthorized: This code indicates that authentication is required for the resource. The client can try again with appropriate authentication.
  • 403 Forbidden: This code indicates that the server is refusing to respond to the request even if the request is valid. The reason will be listed in the body content if the request is not a HEAD method.
  • 404 Not Found: This code indicates that the requested resource is not found at the location specified in the request.
  • 405 Method Not Allowed: This code indicates that the HTTP method specified in the request is not allowed on the resource identified by the URI.
  • 408 Request Timeout: This code indicates that the client failed to respond within the time window set on the server.
  • 409 Conflict: This code indicates that the request cannot be completed because it conflicts with some rules established on resources, such as validation failure.
• 5xx Server Error: This series of status codes indicates server failures while processing a valid request. Here is one of the frequently used status codes in this class:
  • 500 Internal Server Error: This code indicates a generic error message, and it tells that an unexpected error occurred on the server and that the request cannot be fulfilled.

With this topic, we have finished the crash course on HTTP basics. We will be resuming our discussion on RESTful web services in the next section. Take a deep breath and be ready for an exciting journey.

Before getting into the details of REST-enabled web services, let's take a step back and define what a web service is. Then, we will see what makes a web service RESTful.

A web service is one of the most popular methods of communication between the client and server applications over the internet. In simple words, web services are web application components that can be published, found, and used over the web. Typically, a web service has an interface describing the web service APIs, which is known as Web Services Description Language (WSDL). A WSDL file can be easily processed by machines, which blows out the integration complexities that you may see with large systems. Other systems interact with the web service by using Simple Object Access Protocol (SOAP) messages. The contract for communication is driven by the WSDL exposed by the web service. Typically, communication happens over HTTP with XML in conjunction with other web-related standards.

What kind of problems do the web services solve? There are two main areas where web services are used:

• Many of the companies specializing in internet-related services and products have opened their doors to developers using publicly available APIs. For instance, companies such as Google, Yahoo, Amazon, and Facebook are using web services to offer new products that rely on their massive hardware infrastructures. Google and Yahoo offer their search services, Amazon offers its on-demand hosting storage infrastructure, and Facebook offers its platform for targeted marketing and advertising campaigns. With the help of web services, these companies have opened the door to the creation of products that did not exist some years ago.
• Web services are being used within enterprises to connect previously disjointed departments such as marketing and manufacturing. Each department or Line Of Business (LOB) can expose its business processes as a web service, which can be consumed by the other departments.

• By connecting more than one department to share information by using web services, we begin to enter the territory of Service-Oriented Architecture (SOA). SOA is essentially a collection of services, each talking to one another in a well-defined manner, in order to complete relatively large and logically complete business processes.

All these points lead to the fact that web services have evolved as a powerful and effective channel of communication between client and server over a period of time. The good news is that we can integrate RESTful systems into a web service-oriented computing environment without much effort. Although you may have a fair idea of RESTful web services by now, let's see the formal definition before proceeding further.

Remember that REST is not the system's architecture in itself, but it is a set of constraints that when applied to the system's design leads to a RESTful architecture. As our definition of a web service does not dictate the implementation details of a computing unit, we can easily incorporate RESTful web services to solve large-scale problems. We can even fully use RESTful web services in the larger umbrella of the SOA, given that it inherently meets the basic values of SOA, as depicted in the following image:

With this larger view of SOA, we begin to see how REST has the potential to impact the new computing models being developed.

Having learned the basics of a RESTful system, you are now ready to meet more exciting concepts around REST. In this section, you will learn the core architectural elements that make a system RESTful.

Analogous to any software architecture, the REST architecture is also defined by a configuration of key architectural elements (components, connectors, and data) with a set of constraints, as shown in the following diagram:

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components, which abstracts the information being transmitted. A uniform interface is fundamental to the architecture of any RESTful system. In plain words, this term refers to a generic interface to manage all interactions between a client and server in a unified way. All resources (or business data) involved in the client-server interactions are dealt with a fixed set of operations. The following are the core elements that form a uniform interface for a RESTful system:

• Resources and their identifiers
• The representation of resources
• Generic interaction semantics for the REST resources
• Self-descriptive messages
• Hypermedia as the engine of an application state

Let's look at these items in detail in the following section.

A RESTful resource is anything that is addressable over the web. By addressable, we mean resources that can be accessed and transferred between clients and servers. Subsequently, a resource is a logical, temporal mapping to a concept in the problem domain for which we are implementing a solution.

Here are some examples of REST resources:

• A news story
• The temperature in NY at 4:00 p.m. EST
• A tax return stored in the IRS database
• A list of code revision history in a repository such as SVN or CVS
• A student in a classroom in a school
• A search result for a particular item in a web index, such as Google

Even though a resource's mapping is unique, different requests for a resource can return the same underlying binary representation stored in the server. For example, let's say we have a resource within the context of a publishing system. Then, a request for the latest revision published and the request for revision number 12 will at some point in time return the same representation of the resource. In this example, the last revision is version 12. However, when the latest revision published is increased to version 13, a request to the latest revision will return version 13, and a request for the revision of version 12 will continue returning version 12. This implies that in a RESTful architecture, each resource can be accessed directly and independently, and sometimes, different requests may point to the same resource.

As we are using HTTP to communicate, we can transfer a variety of data types between clients and servers, as long as the data type used is supported by HTTP. For example, if we request a text file from CNN, our browser receives a text file. If we request a Flash movie from YouTube, our browser receives a Flash movie. The data is streamed in both cases over TCP/IP and the browser knows how to interpret the binary streams because of the Content-Type header present in the HTTP response header. Following this principle, in a RESTful system, the representation of a resource in the response body depends on the desired internet media type, which is specified within the request header sent by the client.

A URI is a string of characters used to identify a resource over the web. In simple words, the URI in a RESTful web service is a hyperlink to a resource, and it is the only means for clients and servers to exchange representations.

The client uses a URI to locate the resources over web, sends a request to the server, and reads the response. In a RESTful system, the URI is not meant to change over time as it may break the contract between the client and server. More importantly, even if the underlying infrastructure or hardware changes (for example, swapping the database servers) for a server hosting the REST APIs, the URIs for the resources are expected to remain the same as long as the web service is up and running.

The representation of resources is what is sent back and forth between clients and servers in a RESTful system. A representation is a temporal state of the actual data located in a storage device at the time of request. In general terms, it is a binary stream, together with its metadata, which describes how the stream is to be consumed by the client. The metadata can also contain extra information about the resource, for example, validation, encryption information, or extra code to be executed at runtime.

Throughout the life of a web service, there may be a variety of clients requesting resources. Different clients can consume different representations of the same resource. Therefore, a representation can take various forms, such as an image, a text file, an XML, or a JSON format. However, all clients will use the same URI with appropriate Accept header values for accessing the same resource in different representations.

For the human-generated requests through a web browser, a representation is typically in the form of an HTML page. For automated requests from other web services, readability is not as important, and a more efficient representation, such as JSON or XML, can be used.

In the previous sections, we introduced the concepts of resources and representations. We learned that resources are mappings of the actual entity states that are exchanged between clients and servers. Further, we discussed that representations are negotiated between clients and servers through the communication protocol (HTTP) at runtime. In this section, you will learn about the generics of interaction semantics and self-descriptive messages followed for the client-server communication in a RESTful system.

Developing RESTful web services is similar to what we have been doing up to this point with our web applications. In a RESTful web service, resources are exchanged between the client and the server, which represent the business entities or data. HTTP specifies methods or actions for the resources. The most commonly used HTTP methods or actions are POST, GET, PUT, and DELETE. This clearly simplifies the REST API design and makes it more readable. On the other hand, in traditional application development, we can have countless actions with no naming or implementation standards. This may call for more development effort for both the client and the server and make the APIs less readable.

In a RESTful system, we can easily map our CRUD actions on the resources to the appropriate HTTP methods such as POST, GET, PUT, and DELETE. This is shown in the following table:

In fact, the preceding list of HTTP methods is incomplete. There are some more HTTP methods available, but they are less frequently used in the context of RESTful implementations. Of these less frequent methods, OPTIONS and HEAD are used more often than others. So, let's glance at these two method types:

• OPTIONS: This method is used by the client to determine the options or actions associated with the target resource, without causing any action on the resource or retrieval of the resource
• HEAD: This method can be used for retrieving information about the entity without having the entity itself in the response

In their simplest form, RESTful web services are networked applications that manipulate the state of resources. In this context, resource manipulation means resource creation, retrieval, updation, and deletion. However, RESTful web services are not limited to just these four basic data manipulation concepts. They can even be used for executing business logic on the server but remembering that every result must be a resource representation of the domain at hand.

A uniform interface brings all the aforementioned abstractions into focus. Consequently, putting together all these concepts, we can describe RESTful development with one short sentence--we use URIs to connect clients and servers in order to exchange resources in the form of representations.

Let's now look at the four HTTP request types in detail and see how each of them is used to exchange representations to modify the state of resources.

The GET method is used to retrieve resources. Before digging into the actual mechanics of the HTTP GET request, we first need to determine what a resource is in the context of our web service and what type of representation we are exchanging.

For the rest of this section, we will use the example of a RESTful web service handling the department details for an organization. For this service, the JSON representation of a department looks as follows:

{"departmentId":10,"departmentName":"IT","manager":"John Chen"} 

The JSON representation of the list of departments looks as follows:

[{"departmentId":10,"departmentName":"IT","manager":"John Chen"}, 
{"departmentId":20,"departmentName":"Marketing","manager":"Ameya 
   J"}, 
{"departmentId":30,"departmentName":"HR","manager":"Pat Fay"}] 

With our representations defined, we can now assume URIs of the form http://www.packtpub.com/resources/departments to access a list of departments, and http://www.packtpub.com/resources/departments/{name} to access a specific department with a name (unique identifier).

We can now begin making requests to our web service. For instance, if we wanted a record for the IT department, we make a request to the following URI: http://www.packtpub.com/resources/departments/IT.

A representation of the IT department at the time of the request may look like the following code snippet:

{"departmentId":10,"departmentName":"IT","manager":"John Chen"} 

Let's have a look at the request details. A request to retrieve the details of the IT department uses the GET method with the following URI: http://www.packtpub.com/resources/departments/IT

Let's see what happens when a client requests for the IT department with the aforementioned URI. Here is the sequence diagram for the GET request:

What is happening here?

1. A Java client makes an HTTP request with the GET method type and IT as the identifier for the department.
2. The client sets the representation type that it can handle through the Accept request header field. This request message is self-descriptive:

• • It uses a standard method (the GET method in this example) with known semantics for retrieving the content
  • The content type is a set to a well-known media type (text/plain)
  • This request also declares the acceptable response format

3. The web server receives and interprets the GET request to be a retrieve action. At this point, the web server passes control to the underlying RESTful framework to handle the request. Note that RESTful frameworks do not automatically retrieve resources, as that is not their job. The job of a framework is to ease the implementation of the REST constraints. Business logic and storage implementation is the role of the domain-specific Java code.
4. The server-side program looks for the IT resource. Finding the resource could mean looking for it in some data store such as a database, a filesystem, or even a call to a different web service.
5. Once the program finds the IT department details, it converts the binary data of the resource to the client's requested representation. In this example, we use the JSON representation for the resource.
6. With the representation converted to JSON, the server sends back an HTTP response with a numeric code of 200 together with the JSON representation as the payload. Note that if there are any errors, the HTTP server reports back the proper numeric code, but it is up to the client to correctly deal with the failure. Similar to the request message, the response is also self-descriptive.

All the messages between a client and server are standard HTTP calls. For every retrieve action, we send a GET request, and we get an HTTP response back, with the payload of the response being the representation of the resource or, if there is a failure, a corresponding HTTP error code (for example, 404 if a resource is not found or 500 if there is a problem with the Java code in the form of an exception).

Getting a representation for all the departments works in the same way as getting the representation for a single department, although we now use the URI as http://www.packtpub.com/resources/departments and the result is the JSON representation, which looks as follows:

[{"departmentId":10,"departmentName":"IT","manager":"John Chen"}, 
{"departmentId":20,"departmentName":"Marketing","manager":"Ameya 
   J"}, 
{"departmentId":30,"departmentName":"HR","manager":"Pat Fay"}] 

For a request to be safe, it means that multiple requests to the same resource do not change the state of the data in the server. Assume that we have a representation, R, and requests happen at time t. Then, a request at time t1 for the resource R returns R1; subsequently, a request at time t2 for the resource R returns R2, provided that no further update actions have been taken between t1 and t2. Then, R1 = R2 = R.

For a request to be idempotent, multiple calls to the same action should not change the state of the resource. For example, multiple calls to create the resource R at times t1, t2, and t3 means that R will exist only as R and the calls at times t2 and t3 are ignored.

The POST method is used to create resources. As we are creating a department, we use the HTTP POST method. Again, the URI to create a new department in our example is http://www.packtpub.com/resources/departments. The method type for the request is set by the client.

Assume that the Sales department does not exist in our list, and we want to add it to the list. The Sales data representation looks like the following:

{"departmentName":"Sales","manager":"Tony Greig"} 

Now, the sequence diagram of our POST request looks like the following:

The series of steps for the POST request is as follows:

1. A Java client makes a request to the http://www.packtpub.com/resources/departments URI with the HTTP method set to POST.
2. The POST request carries the payload along with it in the form of a JSON representation of the Sales department.
3. The server receives the request and lets the REST framework handle it; our code within the framework executes the proper commands to store the representation, irrespective of which data persistence mechanism is used.
4. Once the new resource is stored, a response code, 2xx (representing successful operation), is sent back. In this example, the server sends 201 Created, which implies that the server has fulfilled the request by creating a new resource. The newly created resource is accessible by traversing the URI given by a Location header field. If it fails, then the server sends the appropriate error code.

The PUT method is used to update resources. To update a resource, we first need its representation in the client. Then, at the client level, we update the resource with the new value(s) that we want. Finally, we update the resource by using a PUT request together with the representation as its payload.

In this example, let's add a manager to the Sales department, which we created in the previous example.

Our original representation of the Sales department is as follows:

{"departmentId":40,"departmentName":"Sales","manager":"Tony 
   Greig" }

Let's update the manager for the Sales department; our representation is as follows:

{"departmentId":40,"departmentName":"Sales","manager":"Ki Gee"} 

We are now ready to connect to our web service to update the Sales department by sending the PUT request to http://www.packtpub.com/resources/departments/Sales. The sequence diagram of our PUT request is as follows:

The series of steps for the PUT request is as follows:

1. A Java client makes a PUT request to http://www.packtpub.com/resources/departments/Sales with the JSON payload representing the modified department details.
2. The server receives the request and lets the REST framework handle it. At this point, we let our code execute the proper commands to update the representation of the Sales department. Once completed, a response is sent back. The 204 No Content response code indicates that the server has fulfilled the request but does not return the entity body.

The DELETE method is used to delete the resource. In this example, we will delete a resource by making use of the same URI that we used in the other three cases.

Assume that we want to delete the Sales department from the data storage. We send a DELETE request to our service with the following URI: http://www.packtpub.com/resources/departments/Sales

The sequence diagram for our DELETE request is shown in the following diagram:

The series of steps for the DELETE request is as follows:

1. A Java client makes a DELETE request to http://www.packtpub.com/resources/departments/Sales.
2. The server receives the request and lets the REST framework handle it. At this point, the server code executes the proper commands to delete the representation of the Sales department.
3. Once completed, a response is sent back.

With this, we have covered all the major actions that can be carried out on resources in a RESTful web service. To keep things simple during our discussion, we did not talk about the actual implementation of the CREATE, READ, UPDATE, and DELETE operations on the resource. In all three examples, we presumed that we have a well-behaved web service that adheres to the RESTful guidelines, and the client and server communicate over HTTP. We use the communication protocol to send action requests, and our resource representations are sent back and forth through unchanging URIs. We will cover more detailed end-to-end examples later in this book.

Hypermedia as the Engine of Application State (HATEOAS) is an important principle of the REST application architecture. The principle is that the model of application changes from one state to another by traversing the hyperlinks present in the current set of resource representations (model). Let's learn this principle in detail.

In a RESTful system, there is no fixed interface between the client and the server, as you may see in a conventional client-server communication model such as Common Object Request Broker Architecture (CORBA) and Java Remote Method Invocation (Java RMI). With REST, the client just needs to know how to deal with the hypermedia links present in the response body; next, the call to retrieve the appropriate resource representation is made by using these dynamic media links. This concept makes the client-server interaction very dynamic and keeps it different from the other network application architectures.

Here is an example illustrating the HATEOAS principle. In this example, the http://www.packtpub.com/resources/departments/IT URI returns the following response to the client:

{"departmentId":10, 
"departmentName":"IT", 
"manager":"John Chen, 
"links": [ { 
        "rel": "employees", 
        "href": "http://packtpub.com/resources/departments/IT/employees" 
    } ]"} 

This is the current state of the system. Now, to get the employees belonging to the department, the client traverses the hyperlink present in the response body, namely http://www.packtpub.com/resources/departments/IT/employees. This URI returns the following employee list. The application state now changes into the following form (as represented by the response content):

[{"employeeId":100, 
 "firstName":"Steven", 
 "lastName":"King", 
 "links": [ { 
        "rel": "self", 
        "href": "http://www.packtpub.com/resources/employees/100" 
    }] 
 }, 
{"employeeId":101, 
"firstName":"Neena", 
"lastName":"Kochhar", 
"links": [ { 
        "rel": "self", 
        "href": "http://www.packtpub.com/resources/employees/101" 
     }] 
 }] 

In this example, the application state changes from one state to another when the client traverses the hypermedia link. Hence, we refer to this implementation principle as HATEOAS.

Connectors provide decoupling between components by encapsulating the underlying implementation of resources and communication mechanisms using various connector types, as described in the following table:

Software components required for REST are categorized by their roles as follows:

As you may know, WSDL is used for describing the functionality offered by a SOAP web service. For a SOAP web service, this is a widely accepted standard and is supported by many enterprises today. In contrast, there is no such standard for RESTful web services, and you may find different metadata formats used by various enterprises.

However, in general, you may see the following goals in common among all these metadata formats for RESTful APIs, although they differ in their syntax and semantics:

• Entry points for the service
• Resource paths for accessing each resource
• Allowed HTTP methods to access these resources, such as GET, POST, PUT, and DELETE
• Additional parameters that need to be supplied with these methods, such as pagination parameters, while reading large collections
• Format types used for representing the request and response body contents such as JSON, XML, and TEXT
• Status codes and error messages returned by the APIs
• Human readable documentation for REST APIs, which includes documentation of the request methods, input and output parameters, response codes (success or error), API security, and business logic

Some of the popular metadata formats used for describing REST APIs are Web Application Description Language (WADL), Swagger, RESTful API Modeling Language (RAML), API Blueprint, and WSDL 2.0.

Over the last few years, the REST architectural style has become very popular in the industry and many enterprises have accepted it as the existent standard for building public web APIs, particularly when scalability and simplicity are major concerns for them. Today, one may see many tools and frameworks available in the market for building RESTful web services. In this section, we will briefly discuss some popular Java-based frameworks and tools for building RESTful systems.

The Java API for RESTful Web Services (JAX-RS) is the Java API for creating RESTful web services following the REST architectural pattern discussed in this chapter. JAX-RS is a part of the Java Platform Enterprise Edition (Java EE) platform and is designed to be a standard and portable solution. There are many reference implementations available for JAX-RS today. Some of the popular implementations are Jersey, Apache CXF, RESTEasy, and Restlet. At this juncture, it is worth mentioning that most of the frameworks in the preceding list, such as Jersey and Apache CXF, are not just limited to reference implementations of the JAX-RS specifications but they also offer many additional features on top of the specifications.

Apart from the JAX-RS-based frameworks (or extensions built on top of JAX-RS), you may also find some promising nonstandard (not based on JAX-RS) Java REST frameworks in the market. Some such frameworks are as follows:

• One such framework is RESTX, which is an open source Java REST framework and is primarily focused on the server-side REST API development. This is relatively new in the market and simplifies the REST API development.
• Spark is another framework that falls in this category. It is a Java web framework with support for building REST APIs. Spark 2.0 is built using Java 8, leveraging all the latest improvements of the Java language.
• Play is another framework worth mentioning in this category. It is a Java (and Scala)-based web application framework with inherent support for building RESTful web services.

Discussing all these frameworks does not come under the scope of this book. We will focus on some of the popular frameworks with many real-life use cases in mind. In the coming chapters, you will learn JAX-RS as well as the additional features available with the Jersey framework for building scalable and maintainable RESTful web services.

This chapter is intended to give an overview of RESTful web services. This is essential for an easy understanding of what you will learn in the rest of the book. As we have just started our topic, we have not covered any code samples in this chapter to keep it simple. In the following chapters, we will examine popular Java tools and frameworks available for building a RESTful web service along with many real-life examples and code samples.

In the next chapter, we will discuss the JSON representation of the REST resources and the Java APIs for JSON processing.