LinkApi Blog

The anatomy of a RESTful API

Technical

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.

Image showing how a RESTful API intermediates information between databases and other devices, such as web apps, mobile apps and other APIs.

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 endpoint

The URL is nothing more than the way to make the request. Let's talk now about what your structure is:

Base URL

This is the beginning of the request URL. Here, you basically inform the domain that repeats itself in any request. For example:

https://api.minhagastronomia.com

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:

https://api.minhagastronomia.com/vinhos

Query String

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:

https://api.minhagastronomia.com/vinhos?pais=brasilegiao=sul

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

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

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:

"Authorization: token123242343534."

Body

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.

Authentication

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:

Basic authentication

Based on user and password encoded in Base64 and used in the request header.

Secret token

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.

Conclusion

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!

Thiago Lima

Thiago Lima is the CEO and founder of LinkApi. Programmer since the age of 12 and entrepreneur since the age of 17, he is a reference in the subject of APIs and Integrations, careers for developers and entrepreneurship.

The best about APIs and Integrations in your inbox

Stay on top of the news and best practices

Solve your integration challenges

Revolutionize your projects and business

Recommended Contents

Share via
Copy link
Powered by Social Snap