A estrutura de uma API REST

Por Monica Nietsche em

Nos dias de hoje, um bom programador deve conhecer nem que seja conceitos básicos e a estrutura de uma API REST ful.

E de acordo com uma pesquisa recente da Pusher, um desenvolvedor nos EUA usa em média 18 APIs para construir sua aplicação. Da mesma forma, 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).

O que é uma API RESTful?

O que quer dizer API (Application Programming Interface) ? É 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.

Vamos dizer que você tenha um sistema com banco de dados e ocorra a necessidade que outras empresas e pessoas tenham acesso a suas informações.

Pronto, é aí que entram as APIs.

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

O primeiro ponto a esclarecer: quando falamos de APIs, toda a comunicação dessa interface é feita via web. Quer dizer, 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

A URL nada mais é, que o caminho para fazer a requisição.

Estrutura da URL – endpoint

  • Base URL

É o início da URL da requisição. Aqui, você basicamente informa o domínio que se repete em qualquer requisição.

  • Resource ou Path

O resource (recurso) é o tipo de informação que você está buscando. Em primeiro lugar, eu simularei buscas de informações sobre vinhos e acrescentarei o resource vinhos:

  • Query String

A query string contém os parâmetros da requisição.

No entanto, se eu quiser saber os melhores vinhos da região sul do Brasil, eu incluirei os parâmetros  e nossa URL ficará 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: Não se utiliza a Query String somente para filtros. Ela é 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)

Headers (cabeçalhos)

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

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

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

“Authorization: token123242343534”.

Body

O body é o corpo da mensagem que você quer enviar na requisição.

Então, utilizarei o body somente nos métodos de POST, PUT, PATCH, porque ele contém o dado a processar pela API, e por isso o body 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 (Http status codes) que podem ser utilizados.

Os status codes 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).

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

Acima de tudo, a autenticação é uma segurança para nossas APIs, porque os dados da API são expostos na WEB.

  • Basic authentication (autenticação Básica)

É uma Autenticação baseada em usuário e senha codificados em Base64 e utilizado no header da requisição.

  • Secret token

É o Token de acesso que se limita ao escopo, assim será enviado na requisição pelo Header ou pela Query String.

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

FONTE: Blog LinkApi Solutions


4 comentários

Anderson · Junho 26, 2021 às 3:47 am

Parabéns pelo post.

    Monica Nietsche · Julho 20, 2021 às 2:53 pm

    Obrigada Anderson!! Bom saber que está sendo útil 🙂

Kaik · Outubro 2, 2020 às 7:07 pm

Vc usou o Tema Hestia do wordpress….muito bom esse tema , parabens pelo artigo !!!!

    Monica Nietsche · Outubro 2, 2020 às 7:16 pm

    Olá Kaik
    Já usei o mesmerize e vi a diferença quando mudei pro Hestia, é muito fácil e prático de mexer.
    Agradeço e ficamos muito feliz que os nossos posts ajudam e se integram com as pessoas!!
    Ótimo fim de semana

Os comentários estão fechados.