Part 1: What is REST In this part, we will take a detailed look at how communication between a client and a server takes place. Along the way, we will reveal new terms and give explanations to 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 can store information about customers and their orders. Those. our system is able to manipulate some entities: create them, edit them, delete them, give out information about them. These entities will be:
clients - clients;
orders - customer orders;
items - goods.
In the REST architecture, clients send requests to the server to retrieve or modify data, and servers send responses to their requests to clients.
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 in more detail.
URIs and Resources
Data that clients receive or change through requests is called a resource. The basis of client-server interaction is the manipulation of resources. Resources in REST are anything that can be given a name. It's kind of like classes in Java. In Java, we can create a class for anything. So in REST, anything can be a resource: a user, a document, a report, an order. All this can be either an abstraction of some entity, or something specific, for example, a file - a picture, video, animation, PDF file. In our example, we have 3 resources:
clients - clients;
orders - customer orders;
items - goods.
Clients send requests to so-called endpoints, or endpoints. To put it very simply, an endpoint is something like an address on the network. Going deeper, we can say that an endpoint is a URI: A sequence of characters that identifies an abstract or physical resource. Uniform Resource Identifier - Uniform Resource Identifier. Sometimes the endpoint, or URI is called a path (path) - the path to the resource. For the purposes of this article, we will use the term URI. Each specific resource must have a unique URI. It is the responsibility of the server developer to ensure that each resource always has its own URI. In our example, we are the developers, so we will do it the best we can. Just as in a relational database it is often customary to specify some numeric ID as the primary key, in REST each resource has its own ID. It often happens that the resource ID in REST is the same as the record ID in the database that stores information about this resource. REST URIs typically begin with the plural form of a noun that describes a resource. For example, from the word clients. Further, through a slash, indicate ID - the identifier of some 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 continue the URI by adding orders to it:
/clients/4/orders - URI of all orders of client #4;
/clients/1/orders/12 — Order URI #12 of client #1.
If we continue this chain and add more products, we get:
/clients/1/orders/12/items - URI of a list of all items in order #12 made by customer #1.
With nesting levels, the key is to make URIs intuitive.
HTTP method
HTTP method (eng. HTTP Method) - a sequence of any characters, except for control and delimiters, which indicates the main operation on the resource. There are several common HTTP methods. We list those that are most often used in RESTful services:
GET - serves to obtain information about a specific resource (via ID) or about a collection of resources;
POST - used to create a new resource;
PUT - is used to change the resource (via ID);
DELETE - is used to delete a resource (via ID).
Titles
In requests, as well as in responses, there are HTTP headers. They send additional information about the request (or response). Headers are key-value pairs. You can read a list of the most common titles on the Wikipedia page . With respect to REST, clients can often send an Accept header in a 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 list of MIME types. MIME(Eng. Multipurpose Internet Mail Extensions - multi-purpose Internet mail extensions) - 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:
This header tells the server that the client is expecting 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 generally do not contain any request body. But PUT and POST can contain: it's all about the functional purpose of the request type. Indeed, to receive data and delete by id (which is passed 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. Same as for modifying an existing resource. REST most often uses XML or JSON formats to pass the request body. The most common format is JSON. Suppose we want to send a request to the server, and in it we want to create a new resource. In case you haven't forgotten, we used an application that manages customer orders as an example. Let's say we want to create a new client. In our case, we store the following information about customers: Name Email Phone number Then the body of such a request can be the following JSON:
Edit customer #1 as follows:
Name - Ben
Email - bigben@jr.com
Tel. — +380 (190) 346-42-13
DELETE /clients/12/orders/6
Delete order #6 from customer #12 from the system
Answers
Let's say a few words about server responses. The answer usually consists of the following parts:
response code;
headings;
response body.
In general, response headers are not much different from request headers. In addition, some headers are used in both responses and requests. With the response body, too, I think everything is clear. The body often returns the information requested by the client. May return information in the same JSON format on 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 of three decimal digits. The first digit indicates the status class. The response code is usually followed by a space-separated explanatory phrase in English, which explains to the person the reason for such a response. Examples:
201 Created;
401 Unauthorized;
507 Insufficient Storage.
The client learns from the response code about the results of his request and determines what actions to take next. Response codes are divided into several groups:
1XX - information;
2XX - inform about cases of successful acceptance and processing of the client's request;
3XX - tell the client that another request must be made to successfully complete the operation, usually by a different URI;
4XX - client error. For example, a poorly crafted request or the well-known 404 Not Found code that can occur when a client requests a non-existent resource;
5XX is a server error. Returned to the client if the operation fails due to the server's fault.
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 can store information about customers and their orders. Those. our system is able to manipulate some entities: create them, edit them, delete them, give out information about them. These entities will be:
GO TO FULL VERSION