O que é uma API RESTful? Entenda tudo sobre REST e HTTP

Neste artigo você vai entender o que é uma API RESTful e também aprender a utilizar uma API, com os verbos HTTP corretos

Fala programador(a), beleza? Bora aprender mais sobre API, REST e também sobre os verbos HTTP!

Vamos começar do começo, falar um pouco sobre APIs e também explorar o conceito de API

O acrônimo significa Application Programming Interface ou Interface de Programação de Aplicações, em português

Basicamente a API nos dá uma possibilidade de simplificar o desenvolvimento, pois não desenvolvemos telas para cada funcionalidade

E sim integramos o sistema já existente a um outro sistema, que nos dá as respostas que precisamos

Isso pode ser feito de forma ágil, pois APIs costumam seguir um padrão de desenvolvimento, tornando fácil também a troca de uma API que faz o mesmo serviço que a outra

Um exemplo prático de integração e troca de API

Suponha que temos um e-commerce, e ele precisa cotar fretes para o endereço do cliente

Cada transportadora pode ter a sua API, para disponibilizar uma cotação diferente em prazo e também em preço

Isso faz com que não precisamos armazenar essa lógica na nossa aplicação e nem desenvolver essa questão do frete

E até nem faz sentido, pois não sabemos quanto a empresa A ou a empresa B vai demorar ou cobrar

Ou seja, as APIs acabam sendo uma forma fácil de aderir funcionalidades completas para a nossa aplicação

E caso uma dessas empresas não seja mais vantajosas, podemos simplesmente desfazer a integração e integrar com uma outra

Por isso a importância de entender o que é uma API e também como elas funcionam, pois vai te deixar mais seguro para desenvolver os sistemas da empresa que você trabalha ou até mesmo os seus sistemas

E quem faz a API? Existe algum problema?

Com certeza, quem cria a API está disponibilizando acesso a dados importantes e também ao sistema que a API está

Por isso é super importante se atentar nos dados que são enviados, e também com a segurança da API

Por mais que seja comercial, ainda há o problema de algum eventual invasão

Quando desenvolvemos uma API, o cliente é quem integra ou utiliza ela e há uma regra bem clara em TI: não podemos confiar no cliente 🙂

Tipos de API, quais são?

As APIs apesar de serem parecidas em sua construção e arquitetura, pois existe um padrão para isso

Podem diferenciar em seu tipo, que são:

• API pública: uma API que é disponibilizada para qualquer um acessar, as vezes exige algum tipo de autenticação para não evitar abusos, como por token;
• API privada: é quando a API é utilizada para sistemas da própria empresa, sempre vai se exigir algum tipo de autenticação;
• API de terceiros: uma API com fins comerciais para fornecer algum serviço, como o de frete explicado acima, vai ter algum meio de autenticação também;

Comunicação com a API

Em diversos pontos do artigo falamos sobre padrões de desenvolvimento, mas não comentamos quais são eles e como utilizá-los, então vamos lá!

Primeiramente temos que entender a comunicação, como são enviados e recebidos os dados das APIS

Normalmente são por meio de XML ou JSON, estes dois tipos de dados são bem estruturados e também de fácil interpretação

Se você quer entender mais sobre JSON veja este vídeo, vale a pena saber pois é o mais utilizado atualmente e domina a maioria das APIs

E o tal do HTTP?

O HTTP é um protocolo muito importante para a web em geral, significa: Hipertext Transfer Protocol

Ele permite a obtenção de diversos recursos, como HTML para a nossa aplicação e é um recurso super completo e até com seu nível de complexidade

Porém para a nossa alegria, vamos nos atentar a parte das requisições utilizando o HTTP, que são utilizadas pelas APIs, e também uma pequena parte do que forma o HTTP

Dica extra: Recomendo fortemente aprender o HTTP por completo!

As requisições são constituídas em algumas partes:

• Método: o método é uma parte muito importante, vamos determinar se estamos buscando algo ou enviando algo;
• Path: basicamente a URL que estamos acessando;
• Versão do protocolo: qual a versão do HTTP está sendo utilizada;
• Headers: configurações da requisição, como o tipo de dado que estamos enviado (JSON);
• Dados: os dados que estamos querendo enviar para o servidor;

E também precisamos nos atentar as respostas, pois toda requisição recebe uma resposta, mesmo que esta contenha algum erro, como um 404

A resposta é constituída por:

• Código de status: O status enviado do servidor, que pode ser 200 (OK), 404 (Não encontrado), 5xx (Erros relacionados ao servidor) e etc;
• Mensagem do status: A mensagem acompanha o status, descrevendo o que ele representa, como no status 200 recebemos o OK;
• Versão do protocolo: A versão de HTTP que está sendo utilizada, como na requisição;
• Headers: Configurações da resposta, como o tipo de dado (JSON);
• Dados: Dados que são enviados pela resposta, os dados são opcionais;

Os verbos do HTTP

Esta é uma parte da requisição, onde basicamente dizemos ao servidor o que estamos querendo fazer, e tudo por meio de verbos

Em APIs, conhecer os verbos é de suma importância

Os principais são:

• GET: Neste método estamos solicitando algum recurso;
• POST: No POST estamos enviando dados que serão salvos no banco, provavelmente;
• DELETE: Em DELETE estamos querendo remover algum recurso;
• PUT: No PUT estamos atualizando completamente um recurso;
• PATCH: Em PATCH estamos atualizando parcialmente um recurso;
• HEAD: O HEAD é parecido com o GET, porém não recebemos corpo de resposta;
• OPTIONS: E o OPTIONS é onde descrevemos as opções de comunicação;

Ao longo da sua vida como desenvolvedor você vai utilizar muito os verbos, tanto para utilizar uma Application Programming Interface

Como também para desenvolver uma, o que é mais importante ainda: definir corretamente o verbo de cada rota

E o que é REST?

REST é um conceito frequentemente ligado a HTTP e também APIs

É um acrônimo para Representational State Transfer

Ou seja, REST é um padrão que podemos implementar quando criamos uma Interface de Programação, precisamos então seguir algumas diretrizes

Quando criamos uma API que segue todos os conceitos que precisamos aplicar do REST, ela é considerada RESTful

De forma resumida os conceitos são:

• Uniformidade: todas as requisições para o mesmo endpoint, devem receber a mesma resposta, independente de onde vieram;
• Desacoplação: A API deve ser independente de um client, não pode interagir com a aplicação, apenas retornar respostas, baseadas na requisição;
• Stateless: as requisições não tem state, ou seja, cada uma é única e essa responsabilidade de sessão é dada a aplicação que a consulta;
• Cache: Quando possível as respostas devem ser cacheadas, melhorando a performance;
• Arquitetura de camadas: A arquitetura da API pode ser composta por camadas, fazendo com que um componente não possa acessar um superior, sem passar pelo intermediário;
• Code on demand (opicional): Em alguns casos pode haver código que precisa ser executado para rodar (Java applets), nestes casos o código deve rodar por demanda;

Seguindo os princípios acima na sua API, você tem uma API RESTful

Que significa ser bem construída/arquitetada e de fácil manutenção para que possa crescer de forma saudável

Você sempre deve tentar criar a sua API mais RESTful possível, pois são bons princípios a serem aplicados

O que é endpoint?

Foi comentada uma palavrinha mágica acima, o tal do endpoint

Que nada mais é do que a URL que você vai utilizar para acessar o recurso da API

Por exemplo:

• /users – acesso a todos os usuários;
• /users/1 – acesso ao usuário com ID 1;

E é claro que estes endpoints vem acompanhados do domínio da API, que fica algo como:

• https://algumdominio.com/users

Este seria o endpoint que retorna todos os usuários, porém unido com o domínio que é convertido como DNS, servindo para acessar o nosso servidor

E dentro destes endpoints também teremos os verbos que eles aceitam, isso é tratado diretamente na aplicação

Ou seja, mudando o verbo HTTP de um endpoint podemos fazer coisas diferentes, exemplo:

• GET /users/1 – retorna um usuário com id 1;
• DELETE /users/1 – remove o usuário com id 1;
• PATH /users/1 – atualiza usuário com id 1;

Isso é muito comum em APIs, e ajuda também a reduzir a complexidade de quem desenvolve e de quem consome os recursos

Sobre as autenticações com API

Nas APIs temos alguns tipos de autenticação, ou seja, formas de sermos autorizados a acessá-las

Isso por dois motivos: informações restritas e também para limitar a quantidade de acessos, que consome o servidor

Não vamos entrar em super detalhes sobre auth neste tópico, apenas distinguir as existentes

Os principais tipos de autenticação são:

• Basic Authentication: envia-se um usuário e senha por meio dos headers para realizar a autenticação, este método não é recomendado, mas alguns serviços o utilizam;
• Bearer Authentication: é a autenticação por token, é enviado um token ao servidor e ele decodifica o token para checar se é valido e autenticar o usuário, normalmente o token tem um secret;
• API Key: é enviada uma chave na requisição, e no servidor verificamos se a chave é válida, este método é mais utilizado em serviços que são públicos, para evitar abusos;
• OAuth: é um serviço de autenticação, muito utilizado para permitir que você faz cadastro/login em outros sites sem precisar inserir a sua senha (por exemplo: login em um e-commerce pela conta do Facebook)

Na industria de software o padrão de Bearer é muito comum, em conjunto do JWT para gerenciar o token que é transmitido nas requisições

Conhecendo o Postman

Postman é um serviço muito utilizado quando o assunto é API

É um client que podemos utilizar para testar a nossa API de uma forma bem intuitiva, construindo o projeto dentro do programa

Escolhendo qual método vai para qual endpoint, mudando o corpo da requisição

Permite verificar a resposta e o status, enfim é super completo

Este é o Postman:

No começo pode ser um pouco confuso, mas basicamente colocamos o endpoint, o método e clicamos em send

A requisição é enviada e recebemos uma resposta no próprio Postman

Vamos testar uma API!

Para fechar com chave de ouro, vamos realizar testes em uma API real e aberta ao público com o Postman

Utilizaremos todos os conhecimentos aprendidos neste artigo para extrair informações da API

O nome dela é ReqRes, você pode acessar o site oficial clicando aqui, ela é aberta ao público e basicamente nos retorna dados de usuário

Podemos utilizar os verbos GET, POST, DELETE e PUT

Vamos colocar um request para resgatar todos os usuários no Postman, o endpoint será:

https://reqres.in/api/users - GET

Veja a resposta recebida:

Note que alteramos o endpoint, o método padrão já é GET, após clicar em Enviar (botão azul), recebemos informações de 12 usuários, como: id, email, nome e avatar

Este é o nosso primeiro contato prático com uma API real, veja como é facil

Agora vamos cadastrar um usuário, este é o modelo do request e a resposta:

Para realizar esta ação precisamos mudar algumas coisas

• Endpoint: não precisa ser alterado, é o mesmo para resgatar usuários;
• Método: precisamos colocar POST, estamos enviado informações;
• Body: precisamos colocar a opção raw e alterar o tipo de dado para JSON, onde enviamos um JSON válido com os campos de name e job;

Isso resulta em um usuário criado na API, não podemos resgatar pois essa API não salva os dados no sistema, eles apenas nos retornam

Mas podemos resgatar os que já existem assim:

Aqui foi necessário mudar o request para GET, e colocar um id já existente no endpoint, colocamos o id 3

Recebemos então um usuário da API como resposta, este usuário está cadastrado no banco de dados

E assim chegamos ao fim dos nossos testes da API, mas você pode continuar seguindo a documentação oficial deles, que é super acessível e simples 🙂

Conclusão

Neste artigo você aprendeu o que é uma API, e também os recursos que andam em paralelo com ela

O conceito de REST e RESTful, os verbos HTTP para as enviar requisições na API

E também como são formadas as requisições e também as respostas

Por último realizamos alguns testes práticos em uma API pública para poder contextualizar tudo que foi visto na teoria em algo mais ‘físico’, recebendo respostas reais baseadas em nossas requisições via Postman

Confira nossos cursos gratuitos no Youtube, com vídeos todos os dias!

Se inscreva e ative o sininho para receber as notificações e aprender mais ainda sobre desenvolvimento web!

Veja também nosso catálogo de cursos na Udemy, todos com exercícios e projetos práticos, nas mais diversas tecnologias

O link acima contém um cupom de desconto para os cursos!