The first module ended with you creating an HTTP request, sending it, and getting a response.
We will do this many more times in the future. We will send requests to third-party servers. We will make applications that themselves accept such requests and return a response. We will create complex logic for processing requests.
Therefore, it would be good to thoroughly study everything related to these requests, to analyze them in detail. So that you can not just copy the request somewhere and repeat it, but really figure out how it all works.
This is what we will do in the second module. Let’s go!
Let's start with theory.
Learning REST API
REST API basics
If you did your homework in the first module and studied the documentation, you should have noticed the acronym API. Actually, it is the API documentation that is the first thing developers should study if they want to understand the interaction with some service or application on the network.
API - Application Programming Interface. This is a description of the ways in which the client and server can communicate with each other. We open the API documentation and learn from there how to get the necessary data from the server.
We always want this interaction to be simple and understandable. This simplifies the task for both developers (no need to reinvent the wheel when designing a new service) and users (a service is much easier to learn if it works on the same principle as previously familiar services). And here it is worth remembering a new term - REST.
REST - acronym for Representational State Transfer. It may not sound very clear, but simply put, REST is a style of interaction (exchange of information) between a client and a server.
This is not some rigid set of rules and requirements. REST does not force the use of any particular programming language, nor does it bind hands with strict guidelines. REST is called an architectural style and it defines 6 principles that a system architecture must comply with.
Accordingly, an API developed taking into account the principles of REST is called a REST API, and the applications themselves are called RESTful
We will be creating just such RESTful applications, so it is worth discussing the principles that they will comply with right away.
- Client-Server Model. The principle defines the separation of the client and the server, the differentiation of their needs. The client does not have to worry about how the data is stored, the main thing is that it be issued upon request. In turn, the server does not care what the client will do with this data, how to further process and display it. This allows them to develop independently of each other, and improves the scalability of the system.
- Statelessness. This principle means that the server should not "think out" the response based on previous experience with this client. Any request is made in such a way that it contains all the necessary information for its processing, regardless of previous requests.
- Caching. To minimize the transmitted data, there is a caching mechanism. For example, if a logo is displayed on some page, then it makes no sense to request it from the server every time. It does not change so often, it will be enough to get it once and save it on the client's computer, in the cache. But if we need to get information about the current speed of the car, then the cache will not help in any way. This principle determines that the data transmitted by the server should be designated as cacheable or not.
- Uniform interface. The principle defines a single format of client-server interaction. The structure of all requests must be the same. Data must be sent in the same form, regardless of who requests it.
- Layered System. The client and server do not necessarily communicate directly. Data transmission can go through several intermediate nodes. In this case, the system is designed so that neither the client nor the server knows whether they are interacting with the final application or an intermediate node. This allows you to balance the load on the servers, increase scalability.
- Code on demand (optional). The only principle that is not mandatory. According to it, the client can expand its functionality by downloading executable code from the server (for example, scripts). In this case, the code should be executed only on demand.
Not too much theory?
Let's put this into practice.
Creating an API request
Let's open AppMaster, create an API request using it, and get a better understanding of how this request works.
API requests are created in the “Business logic” section, in the “External API Requests” tab.
It's time to click “+ New API Request”.
The name and description can be set to anything, they are for our personal use only.
Let's deal with the data that really matters.
The minimum required to create a request is to specify its Method and address (URL). Let's start with the last one.
URL - Uniform Resource Locator. An address given to a particular resource on the Internet. The most familiar version of such a resource is an HTML page - we enter its URL in the address bar of the browser and open the desired site. At the same time, the resource itself can be anything, a picture, a video, a data set. The main thing is that this resource has a specific pointer - an URL to which you can send a request to get this resource.
Referring to the data at its address, we also indicate the method (you can also say the type) of the request, that is, we indicate what actually needs to be done with this data.
When we sent requests for the task of the first module, we received data. This is the GET method. This method is the most obvious method and also the only required one. Therefore, even if we did not specify it explicitly, it was still assumed by default that this was GET.
Let's see what other methods exist.
The HTTP standard itself does not limit the number of methods that can be used. At the same time, only some of the most standard methods are still used to maintain compatibility. There are 5 different methods that can be used in the AppMaster API requests.
- GET. It's already dealt with. The method requests the provision of a resource, and receives data.
- POST. To take data from somewhere, you first need to place this data there. The POST method does just that. Sends data to the server, creates a resource.
- PUT. Similar to the POST method, but its job is to update the data. It does not create new data, but replaces existing data, updates it.
- DELETE. As the name suggests, it deletes data.
- PATCH. The method is similar to PUT, but is used to partially update the data, rather than replacing it entirely. For example, using the PATCH method, you can change the title of an article, or change the value of some parameter.
It is important to consider the fact that the server is not required to do exactly what is specified in the method at all. We can send the address of some page with the DELETE method, but this does not mean that the server will actually delete it. But, purely theoretically, he can do this with the GET command. Or do not change anything, but at the same time send data in response to POST. Just because the developer configured it that way.
This is where REST comes into play, which says that it's time to agree on the observance of the order, stop the mess and do exactly what is indicated in the method. At the very least, this should be the main task (although not necessarily the only one). E.g., when transferring the content of an article using the GET method, you can at the same time increase the counter of the number of its views by 1.
So, we figured out where the data is located and what can be done with it. Let's go further, let's see what other components the request can have.
URL Params. There are situations where we only know part of the URL. An example is the articles on the Appmaster.io website. The starting address for all articles is the same - https://appmaster.io/en/blog/. But then each article has its own title and, accordingly, its own individual part for the exact indication of this particular article.
In such a situation, URL Params are used. We prescribe the general part immediately, and leave the rest to be decided in the process. As a result, the URL is written in the form https://appmaster.io/ru/blog/:id/
The known part is written as is, and the variable part is placed after the “:” sign. The name of this variable part (already without “:”) is added to the list of parameters. In this case, there can be several variable parts, and their location is anywhere in the URL.
Query Params. Remember when we sent a request to boredapi.com in the first module? And in addition to the address, additional data was prescribed. That was the Query Params.
They are written after the URL and are separated from it by a “?” sign. The name of the parameter, the sign “=” and the value of the parameter itself are indicated. If several parameters are used at once, they are separated by the “&” sign.
However, when specifying parameters in AppMaster, you don't have to think about the request rules. Everything will be properly formatted automatically. You just need to specify the name of the parameter itself and add it to the list.
Query Params are used when the data source is the same, but the data itself can be different. For example, Boredapi contained a huge list of things to do. But we were only interested in those that were intended for one person, and that is what we indicated in the request parameters.
Another option is an access key. You may have used this option in module 1 when referring to Alphavantage. Data could be obtained only after registration and sending a personal key in the request parameters.
Pay attention to the pages that you visit on the Internet, you will probably find various parameters in them too. For example, open the weather page of Ventusky.com, in the query parameters geographic values of latitude and longitude are sent.
Headers. Request headers. Usually headers contain service information about the request (meta-information). Headers allow the server to get more information about the client that is requesting the data. The headers can contain information about which browser is being used, what encoding the response is expected to be in, in what language, the exact time of the request, and more. In the case of access to protected data, the headers may contain an authorization key.
In most cases, headers are optional. Even in the first module, we already made a request where we did not specify any headers (although this does not mean that the request was actually sent without them).
Body. Request body. GET requests usually do without it, but if we want to send some data to the server, send a POST or PUT request, then this data is placed in the request body. At the same time, you can place data of any complexity in the request body, for example, send a video file, and not be limited to some number or a text string.
The Response that comes from the server works almost according to the same scheme. It, for obvious reasons, has no request parameters, but the Headers and the Body are included in the response (although they may be empty).
An important difference is the status of the response.
Status code. It comes in the first line of the server response. The status is a three-digit number (the code itself), followed by a phrase explaining it.
It is by the status code that you can find out about the results of the request and understand what actions should be taken next.
All possible status codes are divided into 5 classes. The first digit of the code determines belonging to a particular class. Let's break them down.
1xx — information codes. Report the progress of the request. In real practice, they are rarely used.
2xx — success codes. They report that everything is in order and the request was completed successfully. In response to a GET request, we usually expect to receive a 200 (OK) code. A successful PUT request sends a 201 (Created) code.
3xx — redirects. Indicate that the request should be sent to a different address. An example is code 301 (Moved Permanently), indicating that the required data is now at a new address (the new address itself is passed in the Location header).
4xx — client error codes. The most famous of them - 404 (Not Found), reports that there is no necessary data at the specified address. Other common cases: 400 (Bad Request, syntax error in the request), 401 (Unauthorized, authentication required for access), 403 (Forbidden, access denied).
5xx — server error codes. Report an error on the server side. As an example: 500 (Internal Server Error, any incomprehensible error that cannot be attributed to known code), 503 (Service Unavailable, the server is temporarily unable to process the request for technical reasons)
At this point, we can assume that we have dealt with the basic information for understanding the REST API and the structure of HTTP requests and responses. It remains to clarify only one point - data types. If you have already tried to create your API request in AppMaster, you probably noticed that all data (in parameters, in headers, in body) asks you to specify not only the name, but also the data type.
It is usually pretty obvious to a human how to work with the data, as there is a certain context. Suppose we know that 2 + 2 = 4. We guess that these are numbers and the result of addition will be another number.
But it may not be numbers, but textual data. Then the result of their addition could be the concatenation of strings and 2 + 2 would turn into “22”. Here, so that the computer does not have to think of anything, there is an exact indication of the data type. And at the same time, other tasks are being solved. For example, protection is provided against entering incorrect data; initially, there’s no opportunity to register an e-mail address in the field intended for entering numbers of a phone number.
There are quite a lot of different data types, now we will consider the most basic ones, and in further modules of the course we will get acquainted with the rest.
String — String data type, plain text with no special formatting.
Integer — Integer data type. Can be used for counters or calculations where fractional numbers are not needed
Float — Floating point number. It is used where increased precision is needed and integer values are not enough.
A logical question may arise here. And why not always use Float, why do we need Integer then? But greater accuracy requires more resources. For some small calculations this may be completely invisible, but in the case of large amounts of data, using a reasonable data type can significantly reduce the requirements for computing power and disk space.
Boolean — boolean data type. The simplest data type. It takes one of two values, which are written as True or False. You can often see the designation in the form of 1 (true) and 0 (false).
Repeat the requests from the homework to the first module by creating them in AppMaster in the External API Requests section.
- Create a request to BoredAPI. Specify at least 5 different parameters from the documentation. Submit several different requests, specifying only the required parameters.
- Create a request to Alphavantage. Use the parameters to get the rates of different currencies in relation to each other.