Nowadays, knowing about the concept of RESTful APIs is a mandatory task for those who are or want to be a good programmer.
According to a recent Pusher survey, a developer in the US uses an average of 18 APIs to build his application. In addition, every year 2,000 new APIs appear.
The market for APIs as a service is expected to exceed $1B by 2020, with an annual growth rate above 30% (Source Technavio).
What is a RESTful API, anyway?
API means "Application Programming Interface", in other words, it is a communication interface between developers.
Regarding REST (Representational State Transfer), it is a set of rules and best practices for the development of these APIs.
Think of the following scenario as a programmer: Imagine that you have a great knowledge of gastronomy, and then you create a database to store this data. But then you realize that other people can benefit from it. Okay, that's where the APIs come in. In this case, you could develop an interface, that is, your API, so that other developers can create applications around this knowledge, for example: wine recommendation, recipe ranking, and so on.
Now let's talk about how a RESTful API works in practice.
The first point that needs to be clarified: when we talk about APIs, all communication of this interface is done via the web. That is, everything is done through a request to a URL, which in turn, brings an answer.
Going back to the previous example, think that you are a developer and want to know the best wines from the southern region of Brazil. In this case you would request this information for a URL of this API, and it would return a response to you. Simple, huh?
Understanding a Request
The URL is nothing more than the way to make the request. Let's talk now about what your structure is:
This is the beginning of the request URL. Here, you basically inform the domain that repeats itself in any request. For example:
Resource or Path
The resource is the type of information you are looking for. Let's simulate that we are looking to know about wines, so we add the wine resource:
The query string contains the parameters of that request. So, if I wanted to know the best wines from the southern region of Brazil, I would include these parameters ?pais=brasil®iao=sul and our URL would look like this:
As you can see above, because these are URL parameters, you use (?) and if you want to use more than one parameter you use (&).
Note: The Query String is not only used for filters. It can be used as paging parameters, versioning, sorting, and more.
The method helps you to inform the type of action you are taking in that request.
Among the main methods, we have:
- Get (Search data)
- Post (Send data)
- Put and Patch (Update Data)
- Delete (Delete data)
OBS: There are several other methods that I won't mention in the article, but in this link you can see the complete list.
Headers or headers allow you to submit additional information on the request. It can be used for numerous functions, such as: authentication, object formatting, and more.
It is not recommended that you create custom headers, and here you can see all usage patterns.
To use it is simple you put the property, followed by two points and the value, all in quotes, example:
The body is the body of the message you want to send in the request. It is only used in the methods POST, PUT, PATCH, that is, it contains the data to be processed by the API, and is therefore not required in methods of reading data.
HTTP Status Codes
In order to facilitate the understanding of API responses there are status code standards that can be used.
The most commonly used codes for responses to a request are 200 (OK), 201 (created), 204 (no content), 404 (not found), 400 (bad request), and 500 (internal server error).
There are several other HTTP protocol response codes that can be used. In this link we have the complete table
By default, success codes have the prefix 20x, 30x redirection, 40x client error and 50x server error codes.
Obviously we can't talk about APIs without security, after all we're talking about the WEB.
As main methods of API authentication, we have:
Based on user and password encoded in Base64 and used in the request header.
Access token that can be limited in scope, and that is sent in the request by the Header or Query String.
In that case, we have famous patterns like Auth and JWT.
And then you got a better understanding of how a RESTful API works?
If you want to understand even more about requests, I recommend looking at a test API so you can "play" with some calls, like this one (https://reqres.in/).
This is the first article in a series about RESTful API, so be sure to comment below and follow our blog for the next posts.
The second in the series is already available here!