Já precisou usar uma API onde nada fazia sentido? Aquele POST que serve para buscar dados, um GET que misteriosamente atualiza o banco, e a documentação que parece ter sido escrita pelo estagiário da TI do além. Pois é, existe um motivo para boas APIs seguirem o padrão REST. Nesta série de artigos, vamos explorar os conceitos fundamentais do REST e mostrar boas práticas para construir APIs RESTful de verdade — daquelas que não fazem o desenvolvedor perder a fé na humanidade.
Se alguém soltar um "Mim dá um copo d’água pra mim", você até entende, mas não consegue evitar aquela coceira no cérebro. A frase tá errada, soa esquisita, e qualquer professor de português teria um mini-infarto.
Com APIs acontece a mesma coisa. Quando alguém manda um POST só para buscar dados, é como ouvir essa frase torta. O servidor até entende, mas não está de acordo com a gramática, ou melhor, com o protocolo.
HTTP, no fim das contas, é só isso: um protocolo de comunicação, assim como o português. Seguir os padrões de escrita significa gastar menos neurônios para decifrar o que está acontecendo.
E quando você trabalha em time, isso não é detalhe. É menos energia desperdiçada tentando adivinhar intenção, menos discussão inútil e mais tempo resolvendo o que realmente importa. Ou seja, o desenvolvimento fica ágil, eficiente e com menos vontade de jogar a API pela janela.
Comunicar
HTTP é, no fim das contas, um protocolo de comunicação. E comunicação nada mais é do que o ato de emitir, transmitir e receber mensagens — seja por fala, escrita, sinais ou símbolos.
O HTTP foi pensado para ser simples e legível. Suas mensagens seguem uma estrutura clara: verbos como GET e POST, ou substantivos como OPTIONS e HEAD. A URL indica o recurso que se deseja acessar, enquanto o HEADER e o BODY carregam informações adicionais para o servidor processar a solicitação.
Ou seja, assim como qualquer linguagem, o protocolo define regras de sintaxe, semântica e organização para que todos possam se entender.
A communication protocol is a system of rules that allow two or more entities of a communications system to transmit information via any kind of variation of a physical quantity. The protocol defines the rules, syntax, semantics and synchronization of communication.
HTTP
APIs e navegadores não trocam figurinhas nem mandam carta registrada. Eles se entendem através de mensagens HTTP. E dentro desse papo existem dois jeitos de falar: Requests (pedidos) e Responses (respostas). Cada um segue seu próprio jeitão, com uma estrutura bem definida.
Uma request, por exemplo, costuma ter este formato:
Na imagem é possível identificar os principais elementos de uma request HTTP:
- Method – O verbo HTTP que define a ação desejada. Abaixo há uma tabela com os métodos mais usados.
- Path – O endereço do resource que você quer acessar.
- Version of the protocol – Indica a versão do HTTP. Hoje, o mais comum ainda é o HTTP/1.1, mas já temos o HTTP/2 e até o gRPC funcionando em cima dele.
- Headers – Carregam informações adicionais que ajudam o servidor a entender e processar a requisição.
- Body – O conteúdo da mensagem, geralmente usado junto com métodos como POST, PUT ou PATCH.
Métodos mais utilizados
| HTTP Method | Descrição |
|---|---|
| OPTIONS | Retorna os métodos HTTP válidos e outras opções disponíveis |
| GET | Recupera um resource |
| HEAD | Recupera apenas os headers de um resource |
| PUT | Atualiza completamente um resource |
| POST | Cria um novo resource |
| DELETE | Remove um resource |
| PATCH | Atualiza parcialmente um resource |
O HTTP é connectionless, ou seja, cada chamada gera obrigatoriamente uma response. Isso acontece mesmo que o cliente já não esteja mais esperando — por exemplo, se o usuário fechou o navegador antes.
Uma response HTTP possui a seguinte estrutura:
Na response HTTP é possível identificar os seguintes elementos:
Versão do protocolo HTTP – Indica qual versão está sendo utilizada.
Status Code – O famoso código de status, que é dividido em categorias:
- 2xx – Sucesso (deu tudo certo).
- 3xx – Redirecionamento (vai procurar em outro lugar).
- 4xx – Erro do cliente (a culpa é sua).
- 5xx – Erro do servidor (a culpa é do server).
Status Message – Uma breve descrição ao lado do Status Code, explicando seu significado.
Headers – Informações adicionais para o cliente, como o formato da resposta ou se o conteúdo pode ser cacheado.
Body – Opcional, traz o conteúdo da resposta dependendo do tipo de requisição.
O que é REST
REST é um estilo de arquitetura que define padrões para a comunicação entre sistemas. Embora seja frequentemente associado ao HTTP, ele não é exclusivo desse protocolo — mas as bases de ambos se alinham muito bem.
Na prática, em uma arquitetura REST, clientes enviam solicitações para recuperar ou modificar recursos, e os servidores respondem a essas solicitações de forma estruturada.
O termo foi criado por Roy Fielding em sua tese de doutorado, no capítulo cinco de Architectural Styles and the Design of Network-based Software Architectures.
REST é o acrônimo de REpresentational State Transfer e se baseia em seis restrições fundamentais:
- Uniform Interface
- Stateless
- Cacheable
- Client-Server
- Layered System
- Code on Demand (opcional)
Não existe uma definição formal para o termo RESTful. O mais aceito atualmente é que uma API HTTP é chamada de RESTful quando segue os princípios definidos pelo REST.
Por que utilizar RESTful?
APIs HTTP são hoje o padrão de comunicação entre sistemas. Afinal, a internet roda sobre HTTP. Arquiteturas modernas, como microsserviços, usam esse protocolo em larga escala. Seguir seus padrões garante que ele cumpra seu principal objetivo: ser simples.
O Uncle Bob, no clássico Clean Code, lembra que gastamos muito mais tempo lendo código do que escrevendo — a proporção é de pelo menos 10 para 1.
Indeed, the ratio of time spent reading vs. writing is well over 10:1. Martin, Robert C. Clean Code (Robert C. Martin Series). Pearson Education.
Agora imagine se cada montadora inventasse um padrão diferente para dirigir. No carro da FIAT o acelerador estaria no pé esquerdo, no da Ford ficaria no meio e, no Peugeot, girar o volante para a direita faria o carro ir para a esquerda. Cada troca de veículo seria um pesadelo, exigindo reaprendizado constante.
Aprender consome energia, e repetir padrões é essencial para reduzir esse gasto. Não é à toa que a humanidade sobrevive porque não precisa reaprender todos os dias a andar, falar ou escovar os dentes.
Seguir padrões, portanto, é mais do que uma questão de organização. É economia de energia, eficiência e previsibilidade.
Princípios do REST
Client-Server – Separar responsabilidades entre frontend e backend. Esse é um conceito simples, mas poderoso: isolamento claro entre camadas traz ganhos em testes, escalabilidade e até na organização dos times dentro da empresa.
Stateless – O servidor não guarda estado entre requisições. Cada chamada do cliente precisa conter todas as informações necessárias para o servidor entendê-la. O estado da sessão fica inteiramente no lado do cliente.
Cacheable – Toda resposta deve indicar, de forma explícita ou implícita, se pode ser armazenada em cache. A responsabilidade de manter e gerenciar esse cache é do cliente.
Uniform Interface – Talvez o princípio mais importante, definido por quatro restrições:
- Identificação de recursos via URI.
- Manipulação por representações (usando verbos HTTP).
- Mensagens autoexplicativas, contendo informação suficiente para o servidor processá-las.
- HATEOAS (Hypermedia As The Engine Of Application State), ou seja, as respostas devem incluir links para recursos relacionados, permitindo que o cliente descubra dinamicamente as possibilidades de interação.
Exemplo simples de HATEOAS:
{
"userName": "bruno",
"email": "[email protected]",
"phoneNumber": "11989500000",
"links": [
{ "href": "/users/10/claims", "rel": "claims", "type": "GET" }
]
}
Outro exemplo, mostrando opções de ação em um recurso:
{
"userName": "bruno",
"status": "Active",
"links": [
{ "rel": "block", "href": "/users/10/block" },
{ "rel": "confirm-email", "href": "/users/10/confirm-email" }
]
}
Assim, o fluxo da aplicação pode ser conduzido pelo servidor em vez de ser rigidamente codificado no frontend.
Comentário do teu Pai: embora o HATEOAS esteja lá, bonitinho na definição original, a verdade é que ele gera mais debate do que adesão. Pouquíssimas APIs no mundo real usam de fato esse negócio, porque ninguém até hoje conseguiu provar a necessidade meio esdrúxula de ficar dizendo explicitamente qual a relação entre itens. Na prática, quase todo mundo finge que não viu essa parte da tese do Fielding e vida que segue.
Layered System – A arquitetura deve ser organizada em camadas independentes. Cada camada só enxerga a imediatamente abaixo dela.
Code on Demand (opcional) – Permite estender funcionalidades do cliente por meio de scripts ou applets enviados pelo servidor.
Resources
REST é resource-based. Mantive o termo em inglês porque ele é central no conceito.
Um resource é a abstração fundamental: qualquer entidade importante o suficiente para ser nomeada e identificada por um URI. Isso pode ser um documento, uma imagem, um serviço temporal (“clima em São Paulo hoje”), uma coleção de outros recursos, ou até mesmo um objeto físico, como uma pessoa.
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. Roy Fielding – Representational State Transfer (REST), Chapter 5
Ou seja, REST não limita a nomenclatura: qualquer coisa identificável por uma URI pode ser tratada como resource. Esse ponto é tão importante que escrevi um artigo específico: REST não é CRUD, aprofundando essa discussão.
Conclusão
Pronto, chegamos ao fim. Se até aqui você não entendeu a diferença entre REST e RESTful, relaxa: você vai continuar chamando qualquer gambiarra com endpoint /doStuff de RESTful e se iludindo que tá tudo certo.
Mas falando sério, o ponto mais importante é: tudo gira em torno de Resources. Esse é o coração da coisa. Se você não entende bem o conceito, suas APIs vão acabar parecendo aquele Frankenstein cheio de métodos que não obedecem padrão nenhum.
Nos próximos posts, vamos falar de práticas reais para construir APIs REST que não façam o desenvolvedor que consome seu serviço querer jogar o monitor pela janela.
Fale conosco 
