A anatomia de uma API RESTful

Técnico

Hoje em dia, conhecer sobre o conceito de APIs RESTful é tarefa obrigatória para quem é ou quer ser um bom programador.

De acordo com uma pesquisa recente da Pusher, um desenvolvedor nos EUA usa em média 18 APIs para construir sua aplicação. Além disso, todo ano surgem 2 mil novas APIs.

O mercado de APIs como serviço espera ultrapassar U$1B até 2020, com taxa de crescimento anual acima de 30% (Fonte Technavio).

Mas afinal, o que é uma API RESTful?

API quer dizer “Application Programming Interface”, em outras palavras, é uma interface de comunicação entre desenvolvedores.

Em relação ao REST (Representational State Transfer), ele é um conjunto de regras e boas práticas para o desenvolvimento dessas APIs.

Pense no seguinte cenário como programador: imagine que você tem um grande conhecimento em gastronomia, e então você cria um banco de dados para armazenar esses dados. Mas depois você percebe que outras pessoas podem se beneficiar disso. Pronto, é aí que entram as APIs. Nesse caso, você poderia desenvolver uma interface, ou seja, sua API, para que outros desenvolvedores possam criar aplicativos ao redor desse conhecimento, por exemplo: recomendação de vinhos, ranking de receitas, e por aí vai.

Imagem mostrando como uma API RESTful faz o intermédio de informações entre os bancos de dados e outros dispositivos, como web apps, aplicativos mobile e outras APIs.

Agora vamos falar de como funciona uma API RESTful na prática.

O primeiro ponto que precisa ser esclarecido: quando falamos de APIs, toda a comunicação dessa interface é feita via web. Ou seja, tudo é feito através de uma requisição a uma URL, que por sua vez, traz uma resposta.

Voltando ao exemplo anterior, pense que você é um desenvolvedor e quer saber dos melhores vinhos da região sul do Brasil. Nesse caso você faria uma requisição dessa informação para uma URL dessa API, e ela te retornaria uma resposta. Simples, não?

Entendendo uma requisição

O endpoint

A URL nada mais é que o caminho para fazer a requisição. Vamos falar agora sobre qual é sua estrutura:

Base URL

Esse é o início da URL da requisição. Aqui, você basicamente informa o domínio que se repete em qualquer requisição. Por exemplo:

https://api.minhagastronomia.com

Resource ou Path

O recurso é o tipo de informação que você está buscando. Vamos simular que estamos buscando saber sobre vinhos, então acrescentamos o recurso vinhos:

https://api.minhagastronomia.com/vinhos

Query String

A query string contém os parâmetros daquela requisição. Portanto, se eu quisesse saber os melhores vinhos da região sul do Brasil, eu incluiria esses parâmetros ?pais=brasil&regiao=sul e nossa URL ficaria assim:

https://api.minhagastronomia.com/vinhos?pais=brasil&regiao=sul

Como podem ver acima, por se tratar de parâmetros da URL, você usa o (?) e caso queira utilizar mais de um parâmetro você utiliza o (&).

OBS: A Query String não é somente utilizada para filtros. Ela pode ser utilizada como parâmetros de paginação, versionamento, ordenação, e muito mais.

O método

O método te ajuda a informar o tipo de ação que você está fazendo naquela requisição.

Dentre os principais métodos, temos:

  • Get (Buscar dados)
  • Post (Enviar dados)
  • Put e Patch (Atualizar dados)
  • Delete (Deletar dados)

OBS: Existem vários outros métodos que não irei citar no artigo, mas nesse link você pode ver a lista completa.

Headers

Headers ou cabeçalhos permitem que você envie informações adicionais na requisição. Ele pode ser utilizado para inúmeras funções, como: autenticação, formatação de objeto, e muito mais.

Não é recomendado que você crie headers customizados, e aqui você pode ver todos os padrões de utilização.

Para utilizá-lo é simples você coloca a propriedade, seguido dois pontos e o valor, tudo entre aspas, exemplo:

“Authorization: token123242343534”.

Body

O body é o corpo da mensagem que você quer enviar na requisição. Ele é utilizado somente nos métodos de POST, PUT, PATCH, ou seja, ele contém o dado a ser processado pela API, e por isso ele não é necessário em métodos de leitura de dados.

HTTP Status Codes

Para facilitar o entendimento das respostas das APIs existem padrões de códigos de status que podem ser utilizados.

Os códigos mais utilizados para as respostas de uma requisição são o 200 (OK), o 201 (created), o 204 (no content), o 404 (not found), o 400 (bad request), e 500 (internal server error).

Existem vários outros códigos de resposta do protocolo HTTP que podem ser utilizados. Nesse link temos a tabela completa

Como padrão, os códigos de sucesso tem o prefixo 20x, os de redirecionamento 30x, os de erro do cliente 40x e os de erro de servidor 50x.

Autenticação

Obviamente não podemos falar de APIs sem segurança, afinal estamos falando da WEB.

Como principais métodos de autenticação de APIs, temos:

Basic authentication

Baseado em usuário e senha codificados em Base64 e utilizado no header da requisição.

Secret token

Token de acesso que pode ser limitado a escopo, e que é enviado na requisição pelo Header ou pela Query String.

Nesse caso temos padrões famosos como oAuth e JWT.

Conclusão

E aí conseguiu entender melhor como funciona uma API RESTful?

Se quiser entender ainda mais sobre os requests, recomendo olhar uma API de testes para você conseguir “brincar” com algumas chamadas, como essa por exemplo (https://reqres.in/).

Esse é o primeiro artigo de uma série sobre API RESTful, portanto não deixe de comentar abaixo e acompanhe nosso blog para os próximos posts.

O segundo da série já está disponível aqui!

Compartilhe

O melhor sobre APIs e Integrações.
Toda semana no seu inbox.

Fique por dentro das novidades e melhores práticas

use o linkapi agora!

Construa integrações gratuitamente

use o linkapi agora

Construa integrações gratuitamente

Thiago Lima

Thiago Lima

Thiago Lima é o CEO e fundador da LinkApi. Programador desde os 12 anos e empreendedor desde os 17, é referência no assunto de APIs e Integrações, carreiras para desenvolvedores e empreendedorismo.
    O melhor sobre APIs e Integrações. Toda semana no seu inbox.

    O melhor sobre APIs e Integrações.

    Toda semana no seu inbox.

    Conteúdos técnicos, novidades sobre integrações, dicas de mercado e mais conteúdos exclusivos!

    Assinatura realizada com sucesso!

    Pin It on Pinterest