Overview of REST. Part 2: Communication between a client and server

Overview of REST. Part 1: What is REST? In this part, we will dive deep into how communication takes place between a client and server. Along the way, we will uncover new terms and explain them. To ensure everything is clear, we will analyze client-server communication using a RESTful application as an example. Suppose we are developing a web application that stores information about customers and their orders. In other words, our system is able to perform operations on certain entities: create, edit, and delete them, and display information about them. These entities will be:

• customers (customers)
• orders (customer orders)
• items (products)

In a RESTful architecture, clients send requests to a server to retrieve or modify data, and then servers send clients responses to their requests.

Requests

Client requests are almost always made using the HTTP protocol. In general, HTTP requests consist of several components:

• HTTP method
• header
• URI
• request body

Below we will consider each component in greater detail.

URIs and resources

The data that clients receive or modify through requests is called resources. Client-server communication is all about manipulating resources. In REST, resources are anything you can give a name to. In a sense, they are like classes in Java. In Java, we can create a class for anything. So in REST, a resource can be anything: a user, a document, a report, an order. It can be either an abstraction of some entity, or something specific, for example, an image, video, animation, or PDF file. In our example, we have 3 resources:

• customers (customers)
• orders (customer orders)
• items (products)

Clients send requests to resource locations known as endpoints. Put simply, an endpoint is like an address on the network. Diving deeper, we can say that an endpoint is a URI, i.e. a sequence of characters that identifies an abstract or physical resource. Uniform resource identifier (URI) Sometimes an endpoint, or URI, is called a path, meaning the path to a resource. For the purposes of this article, we will use the term URI. Each specific resource must have a unique URI. The server developer is responsible for ensuring that each resource always has its own URI. In our example, we are the developers, so we will do it the way we know how. Just as it is often customary to assign numerical identifiers as the primary keys in a relational database, each resource also has its own ID in REST. The resource ID in REST often matches the ID of the record in the database that stores information about the resource. REST URIs customarily start with the plural form of a noun describing some resource. For example, "customers". This is followed by a slash, and then the identifier (ID) of a particular customer. Examples:

• /customers — URI of all available customers
• /customers/23 — URI of a specific customer, i.e. the customer with ID=23
• /customers/4 — URI of a specific customer, i.e. the customer with ID=4.

But that's not all. We can extend the URI by adding orders:

• /customers/4/orders — URI of all orders made by customer No. 4
• /customers/1/orders/12 — URI of order No. 12 made by customer No. 1.

If we continue the expansion by adding more products, we get:

• /customers/1/orders/12/items — URI of the list of all products in order No. 12 made by customer No. 1.

As we add levels of nesting, the important thing is to make the URIs intuitive.

HTTP method

The HTTP method is a sequence of any characters (except for control characters and delimiters), which indicates the main operation being performed on the resource. There are several common HTTP methods. We will list those that are used most often in RESTful services:

• GET — Get information about a particular resource (through its ID) or about a collection of resources
• POST — Create a new resource
• PUT — Change a resource (through its ID)
• DELETE — Delete a resource (through its ID)

Headers

Requests, as well as responses, contain HTTP headers. They convey additional information about the request (or response). Headers are key-value pairs. You can view the list of the most common headers on Wikipedia. As for REST, clients often send an "Accept" header in requests to the server. This header is needed to tell the server what format in which the client expects to receive a response. Various formats are given in a list of MIME types. MIME (Multipurpose Internet Mail Extensions) is a specification for encoding information and formatting messages so they can be sent over the Internet. Each MIME type consists of two parts separated by a slash — a type and subtype. Examples of MIME types for different types of files:

• text — text/plain, text/css, text/html
• image — image/png, image/jpeg, image/gif
• audio — audio/wav, audio/mpeg
• video — video/mp4, video/ogg
• application — application/json, application/pdf, application/xml, application/octet-stream

For example, a request can have a header like this:

Accept:application/json

This header tells the server that the client expects to receive a response in JSON format.

Request body

This is the message sent by the client to the server. Whether the request has a body or not depends on the type of HTTP request. For example, GET and DELETE requests generally do not contain any request body. But PUT and POST requests can — it just depends on the purpose of the request. After all, to receive and/or delete data using an ID (which is passed in the URL), you don't need to send additional data to the server. But in order to create a new resource (through a POST request), you need to send the resource. The same is true for modifying an existing resource. In REST, the request body is most often sent in XML or JSON format. The JSON format is most common. Suppose we want to send a request to the server in order to create a new resource. If you haven't forgotten, we considered the example of an application that manages customer orders. Let's say we want to create a new customer. In our case, we store the following customer information: Name, email, phone number. Then the body of the request could be the following JSON:

{
  "name" : "Amigo",
  "email" : "amigo@jr.com",
  "phone" : "+1 (222) 333-4444"
}

Putting requests together

So, we have examined what might be in a client request. We will now give some examples of requests along with descriptions

Responses

Let's say a few words about server responses. A response usually consists of the following parts:

• response code
• headers
• response body

In general, response headers are not much different from request headers. Additionally, some headers are used in both responses and requests. I think everything is also clear regarding the request body. The body often returns information requested by the client. Information returned in response to GET requests may also be in JSON format. But the last part is a little more interesting.

HTTP response codes

Let's consider HTTP response codes in more detail. An HTTP status code is part of the first line of a server response to requests made via the HTTP protocol. It is an integer consisting of three decimal digits. The first digit indicates the class of the response status code. The response code is usually followed by an explanatory phrase in English, separated by a space. This phrase is a human-readable reason for the response. Examples:

• 201 Created
• 401 Unauthorized
• 507 Insufficient Storage

The response code tells the client the result of the request and allows it to determine what actions to take next. Response codes are divided into several classes or groups:

• 1XX — Informational
• 2XX — These codes indicate that the client's request was successfully received and processed
• 3XX — These codes inform the client that an additional request, usually to a different URI, must be made in order to successfully complete the operation
• 4XX — Client error. Such codes may result from an incorrectly composed request. Another example is the well-known "404 Not Found" code, which can occur when a client requests a nonexistent resource
• 5XX — Server error. These codes are returned to the client if the server is responsible for failure of the operation

Overview of REST. Part 3: Building a RESTful service on Spring Boot