API REST! A moda antiga que não sai de cena
Se algum desavisado manda um POST para pegar dados, dá vontade de jogar o teclado na parede. E se for um GET que mexe no banco, já dá para pensar em usar o teclado na cabeça do desenvolvedor responsável. Vamos entender por que é importante seguir a arquitetura REST, antes que alguém invente moda outra vez.
Alguém pedindo "Mim dá um copo d'água pra mim" soa estranho, né? É a mesma coisa quando você faz POST para buscar dados. Isso é bizarro e só faz os desenvolvedores tomarem café demais. Parem com isso!
O HTTP é igual nossa língua: tem um padrão para ninguém ficar confuso. Seguir o protocolo evita stress e aquelas horas explicando o que era óbvio.
Comunicação (ou quase isso)
HTTP é um protocolo de comunicação. Comunicação é passar e receber mensagens de forma que todo mundo entenda. Não é ficar inventando moda ou mudando as regras no meio do projeto porque achou "legal".
O HTTP foi feito para humanos. Tem verbo, recurso, cabeçalho e corpo.
HTTP (ou como não pirar seu colega)
APIs e browsers trocam mensagens HTTP, como uma conversa entre pessoas civilizadas. Cada pedido tem:
- Method – o que você quer fazer
- Path – onde quer fazer
- Version of the protocol – já chegou no 2, mas você usa o 1.1 porque "tá funcionando bem até agora"
- Headers – umas informações extras
- Body – normalmente só para POST, PUT e PATCH
Métodos básicos para não passar vergonha:
| Método HTTP | O que faz |
|---|---|
| OPTIONS | Pergunta educada para o servidor |
| GET | Busca (e só isso!) |
| HEAD | Busca, mas só dá uma olhada rápida |
| PUT | Atualiza, sem frescura |
| POST | Cria, sem discussão |
| DELETE | Remove |
| PATCH | Atualiza só um pedacinho |
HTTP é sem conexão, então, se você largar o cliente sozinho, o servidor responde de qualquer forma.
O que é REST (e por que você não entendeu até agora)
REST é um estilo de arquitetura criado por Roy Fielding, com regras claras que você ignora toda vez que fala "mas é REST, eu juro!".
São seis restrições principais:
- Interface Uniforme
- Sem estado
- Cacheável
- Cliente-servidor
- Sistema em camadas
- Código sob demanda (opcional)
RESTFul não é o mesmo que REST, mas quem liga. Chamou de RESTFul? Já está no LinkedIn.
Por que usar RESTFul? (Ou por que você não devia inventar moda)
HTTP é o básico, universal e já aprovado. Se ainda gosta de SOAP, parabéns, você está oficialmente velho.
Como diria Uncle Bob em Clean Code:
De fato, a proporção de tempo gasto lendo vs. escrevendo é bem mais que 10:1. Martin, Robert C.. Clean Code (Robert C. Martin Series). Pearson Education.
Você lê muito mais do que escreve código.
Princípios do REST (ou como não ser odiado no projeto)
- Client-Server – frontend não é backend
- Stateless – o servidor não é babá para guardar estado
- Cacheable – não obrigue o servidor a responder a mesma pergunta toda hora
- Uniform interface – menos complicação, mais ação
{
"userName": "bruno",
"email": "[email protected]",
"phoneNumber": "11989500000",
"name": "bruno",
"links": [
{
"href": "10/claims",
"rel": "claims",
"type": "GET"
}
]
}
{
"userName": "bruno",
"status": "Active",
"links": [
{"rel": "block", "href": "/users/10/block"},
{"rel": "confirm-email", "href": "/users/10/confirm-email"}
]
}
- Sistema em camadas – cada camada ignora a próxima
- Código sob demanda – se der errado, culpe o cliente
Recursos (ou o que você pode ter entendido errado)
Tudo no REST gira em torno dos Recursos. Não confunda REST com CRUD.
A chave de abstração de informações no REST é um recurso. — Roy Fielding, CAPÍTULO 5 - Transferência de Estado Representacional (REST)
Conclusão
REST é simples, desde que você não resolva ser criativo demais. Entenda Recursos e pare de complicar o que é fácil.
Nos próximos textos, vamos ver boas práticas reais e espero que você pare de chamar API bagunçada de REST.
Fale conosco