Part 1 — A RESTful API Anatomy

According to a recent Pusher’s research, developers in the USA use an average of 18 APIs to build an application, and every year, new 2 thousand APIs are released.

Besides that, the APIs as a service market expects to reach U$1B by 2020, with an annual growth rate higher than 30%. (Source: Technavio)

Because of that, getting to know the APIs concept is mandatory for everyone who is or aims to be a good developer.

But, what is a RESTful API?

API means “Application Programming Interface”. Or, in other words, it’s an interface dedicated to developers’ communication.

Regarding REST (Representational State Transfer), it is a set of best practices and rules for developing these APIs.

Think about the following scenario as a developer: You are a great gastronomy connoisseur, so you create a database to store information. But later on, you realize that other people can benefit from that. That’s it: that’s when APIs come up. In that case, you can develop an interface (which is your API) to enable other developers to create different applications that share your knowledge. For instance, a wine recommendation app, a recipe app, and so on.

Now, let’s talk about how an API works.

The first thing that needs to be clarified, when we talk about APIs, all of the interface’s communication happens on the web, meaning that everything is done through a URL request, which will bring the required information back.

Back to our previous example, imagine you are a developer and you’re very interested in learning more about the best wines available in Brazil’s southern region. In that case, you would request this information to this API’s URL, and it would return that data. It’s simple, isn’t it?

Understanding a request

The endpoint

The URL can be defined as the path for making a request. It’s relevant highlighting that an URL follows this structure:

• Base URL

That’s the beginning of the URL’s request. Basically, here you will inform the information’s domain that will be the same in any request. For instance:

https://api.mygastronomy.com

• Resource or Path

A resource is the type of information you are looking for. Let’s imagine that we are searching for information about wines, so we’ll add the “wines” resource:

https://api.mygastronomy.com/wines

• Query String

Query strings are the request’s parameters, so, if I wanted to know what are the best wines from Brazil’s southern region, I’d include these parameters: ?country=brazil&region=southern and our URL would be:

https://api.mygastronomy.com/wines?country=brazil&region=southern

As you can see above, because we are talking about URL parameters, you use (?) for one parameter, and (&) if you need more than one.

Note: query strings aren’t restricted to filters. They can be used as pagination parameters, versioning, ordination and many more.

• The Method

Methods help you to inform the kind of action you’re taking on that request.

Among the main ones, we have:

• Get (Search for data)
• Post (Send data)
• Put and Patch (Update data)
• Delete (Delete data)

Note: There are many other methods I won’t go through in this article, but on this link, you can see the whole list.

Headers

Headers allow you to send additional information on your request. It can be used in many functions, like authentication, objects formatting and many more.

It’s not recommended to create custom headers. Here you can see all of the usage patterns.

Headers have a simple usage. You need to inform, in quotes, the property, followed by “: “ and the value, for instance:

“Authorization: token123242343534”.

Body

As the name suggests, it is the body of the message you want to send on your request. Its usage is restricted to “POST” and “PUT” methods, which means that it contains the data that needs to be processed by the API, so that’s why it is not necessary for other data reading methods.

HTTP Status Codes

In order to make your APIs responses easier to understand, there are some patterns to status codes.

The most used ones are 200 (OK), 201 (created), 204 (no content), 404 (not found), and 500 (internal server error).

There are many more HTTP protocol status codes that can be used. Here, we have the full list.

By default, success codes have “20x” prefix, the redirecting ones are “30x”, client errors are “40x”, and server errors are represented by “50x”.

Authentication

Obviously, we cannot talk about APIs without mentioning security. After all, we are talking about the web.

The main methods of API authentication are:

• Basic authentication

It’s based on a username and a password, encoded in Base64 and used on the request’s header.

• Secret token

It’s an access token, that can be limited to a scope, and it’s sent on the request on its header or its Query String.

In this case, we have some famous patterns like oAuth and JWT.

Conclusion

So, did you understand how an API works?

If you want to go deeper and understand more about requests, I recommend you to take a look at this testing API, so you can “play” with some requests: https://reqres.in

This is the first article of a whole API series, so I hope you enjoyed it and I see you on the next one!