Part 1: What is REST In this part we will take a closer look at how communication occurs between the client and the server. Along the way, we will reveal new terms and give explanations for them. To make everything (become) clear, we will analyze client-server communication using the example of some RESTful application. Let's say we are developing a web application that is capable of storing information about customers and their orders. Those. our system is capable of manipulating some entities: creating them, editing them, deleting them, and providing information about them. These entities will be:
clients - clients;
orders - customer orders;
items - goods.
In REST architecture, clients send requests to the server to obtain or modify data, and servers send responses to clients to their requests.
Requests
Client requests are almost always made over HTTP. In general, HTTP requests consist of several components:
HTTP method;
title;
URI;
request body.
Below we will look at each component part in more detail.
URI and Resources
Data that clients obtain or modify through requests is called resources. The basis of client-server interaction is the manipulation of resources. Resources in REST are anything that can be given a name. In a sense, these are like classes in Java. In Java we can create a class for anything. It’s the same in REST - a resource can be anything: a user, a document, a report, an order. All this can be either an abstraction of some entity or something concrete, for example, a file - a picture, video, animation, PDF file. For our example, we have 3 resources:
clients - clients;
orders - customer orders;
items - goods.
Clients send requests to so-called endpoints, or end points. To put it very simply, an endpoint is something like an address on the network. To go deeper, an endpoint is a URI : a sequence of characters that identifies an abstract or physical resource. Uniform Resource Identifier - a unified resource identifier. Sometimes the endpoint, or URI, is called a path - 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 responsibility for ensuring that each resource always has its own URI lies on the shoulders of the server developer. In our example, we are the developers, so we will do it the way we know how. Just as in a relational database it is often customary to set the primary key to a certain numeric ID, in REST each resource has its own ID. It often happens that the ID of a resource in REST matches the ID of the record in the database in which information about this resource is stored. REST URIs usually start with the plural form of a noun that describes some resource. For example, from the word clients. Next, an ID is indicated through a slash - the identifier of a specific client. Examples:
/clients - URI of all existing clients;
/clients/23 - URI of a specific client, namely the client with ID=23;
/clients/4 - URI of a specific client, namely the client with ID=4.
But that's not all. We can extend the URI by adding orders to it:
/clients/4/orders — URI of all orders of client No. 4;
/clients/1/orders/12 - URI of order No. 12 of client No. 1.
If we continue this chain and add goods, we get:
/clients/1/orders/12/items — URI of the list of all products in order No. 12 made by client No. 1.
With nesting levels, the key is to make URIs intuitive.
HTTP method
HTTP Method (English HTTP Method) is a sequence of any characters, except for controls and separators, which indicates the main operation on a resource. There are several common HTTP methods. We list those that are most often used in RESTful services:
GET - used to obtain information about a specific resource (via ID) or a collection of resources;
POST - used to create a new resource;
PUT - used to change a resource (via ID);
DELETE - used to delete a resource (via ID).
Headings
Requests, as well as responses, contain HTTP headers. They send additional information about the request (or response). Headers are key-value pairs. You can read the list of the most common headings on the Wikipedia page . With REST, clients can often send an Accept header in their request to the server. It is needed to let the server know in what format the client expects to receive a response from it. Various format options are presented in the so-called MIME type list. MIME (Multipurpose Internet Mail Extensions) is a specification for encoding information and formatting messages so that they can be sent over the Internet. Each MIME type consists of two parts, separated by a slash: a type and a subtype. Examples of MIME types for different types of files:
In total, the request may have the following header:
Accept:application/json
This header tells the server that the client expects to receive a response in JSON format.
Request body
A message sent by the client to the server. Whether a request has a body or not depends on the type of HTTP request. For example, GET and DELETE requests typically do not contain any request body. But PUT and POST can contain: it’s all about the functional purpose of the request type. After all, to receive data and delete it by id (which is transmitted in the URL), you do not need to send additional data to the server. But to create a new resource (POST request), you need to transfer this resource. The same goes for modifying an existing resource. In REST, XML or JSON formats are most often used to transmit the request body. The most common format is JSON. Suppose we want to send a request to the server, and in it create a new resource. If you remember, as an example we looked at an application that manages customer orders. Let's say we want to create a new client. In our case, we store the following information about clients: Name Email Phone number Then the body of such a request could be the following JSON:
Edit client #1 as follows:
Name - Ben
Email - bigben@jr.com
Tel. — +380 (190) 346-42-13
DELETE /clients/12/orders/6
Delete order No. 6 from customer No. 12 from the system
Answers
Let's say a few words about the server's responses. The answer usually consists of the following parts:
response code;
headers;
response body.
In general, response headers are not much different from request headers. In addition, some headers are used in both responses and requests. I think everything is clear with the body of the response too. The body often returns information that the client requested. Information can be returned in the same JSON format for GET requests. But the last part is a little more interesting.
HTTP response codes
Let's take a closer look at HTTP response codes. Here is a quote from Wikipedia: HTTP status code is part of the first line of the server response for requests via the HTTP protocol. It is an integer with three decimal digits. The first digit indicates the class of the condition. The response code is usually followed by an explanatory phrase in English separated by a space, which explains to the person the reason for this particular response. Examples:
201 Created;
401 Unauthorized;
507 Insufficient Storage.
The client learns from the response code about the results of its request and determines what actions to take next. Response codes are divided into several groups:
1ХХ - informational;
2ХХ - inform about cases of successful acceptance and processing of a client’s request;
3XX - inform the client that in order to successfully complete the operation, it is necessary to make another request, usually using a different URI;
4ХХ - client error. For example, an incorrectly constructed request or the well-known 404 Not Found code, which can occur when a client requests a non-existent resource;
5ХХ - server error. Returned to the client if the operation fails due to the fault of the server.
GO TO FULL VERSION