API REST! Lá vem o hype mais velho da história da programação moderna.
Quando algum infeliz resolve fazer POST pra pegar dados, dá vontade de quebrar o teclado.
Se for um GET que atualiza o banco, quebra o teclado na cabeça do espirito de porco do DEV que fez isso. Então vamos bater aquele papo pra você entender por que é importante seguir a bendita arquitetura REST, antes que você invente moda de novo.
Alguém que fala "Mim dá um copo d'água pra mim" soa meio idiota, não? É exatamente assim que você soa quando faz POST pra buscar dados. É ridículo, me irrita, e faz os desenvolvedores quererem tomar café demais. Parem com isso!
O HTTP é igual português: tem um padrão pra não enlouquecer ninguém. Seguir o protocolo evita desgaste, discussões inúteis e horas gastas explicando coisas óbvias.
Comunicar (ou quase)
HTTP é um protocolo de comunicação. Comunicação, caro gafanhoto, é emitir, transmitir e receber mensagens usando algum meio inteligível. Não é inventar moda nem reescrever a RFC no meio do projeto porque você achou "legal".
O HTTP foi projetado para humanos. Tem verbo, tem recurso, tem cabeçalho, tem corpo. Tá tudo lá pra você não precisar ficar explicando na daily porque sua API não faz sentido nenhum.
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. — Wikipedia - Communication protocol
HTTP (ou como não matar seu colega de raiva)
APIs e browsers trocam mensagens HTTP, tipo conversa civilizada entre adultos (idealmente). Cada request tem:
Mozilla Org
- Method – o que você quer fazer (não inventa!)
- Path – onde quer fazer (não inventa também!)
- Version of the protocol – já está no 2, mas você usa o 1.1 porque "tá funcionando bem até agora"
- Headers – informações extras (tipo o token que você copiou errado)
- Body – geralmente só para POST, PUT e PATCH, e não para seu GET "especial" que você jura que faz sentido (não faz)
Métodos básicos pra não passar vergonha:
| HTTP Method | Descrição |
|---|---|
| OPTIONS | Pergunta educada pro servidor: "que que eu faço agora?" |
| GET | Busca (e só isso!) |
| HEAD | Busca, mas só pra dar uma olhada rápida |
| PUT | Atualiza, sem frescura |
| POST | Cria, sem discussão |
| DELETE | Remove com raiva |
| PATCH | Atualiza só um pedacinho porque tá com preguiça |
HTTP é connectionless, então se você largar o client chorando sozinho, o servidor responde mesmo assim, porque é bem-educado.
Tem status code pra você ignorar e um corpo pra você jurar que vai validar um dia.
O que é REST (e por que você não entendeu direito até agora)
REST não é só hype de arquiteto querendo parecer esperto em conferência. REST é um estilo arquitetural criado por Roy Fielding, com regras claras que você ignora toda vez que fala "mas é REST, eu juro!".
Tem seis restrições principais pra você fingir que entende:
- Uniform Interface (porque padronização não dói)
- Stateless (porque estado é dor de cabeça)
- Cacheable (pra não derrubar servidor toda hora)
- Client-server (cada um com seus problemas, sem misturar)
- Layered System (quanto mais camada, mais job security)
- Code on Demand (essa é opcional, que é pra ninguém te culpar se der errado)
RESTFul não é o mesmo que REST, mas ninguém 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 pelo Uncle Bob. Se você gosta de se torturar com SOAP, parabéns, está oficialmente velho demais.
Como diria Uncle Bob em Clean Code:
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.
Você lê muito mais do que escreve código, então pare de ser esperto demais e siga o padrão.
Princípios do REST (ou como não ser odiado no projeto)
Client-Server – frontend não é backend, aceite isso.
Stateless – o servidor não é babá pra guardar estado.
Cacheable – não obrigue o servidor a responder a mesma pergunta toda hora.
Uniform interface – menos complicação, mais ação.
- Identifique recursos por URI.
- Use verbos HTTP pra manipular recursos.
- Mensagens autoexplicativas (ajude quem vem depois de você).
- HATEOAS (ninguém usa, mas tá aí)
{
"userName": "bruno",
"email": "[email protected]",
"phoneNumber": "11989500000",
"name": "bruno",
"links": [
{
"href": "10/claims", // Pra você não ter que decorar endpoints
"rel": "claims",
"type": "GET"
}
]
}
{
"userName": "bruno",
"status": "Active",
"links": [
{"rel": "block", "href": "/users/10/block"}, // pra facilitar sua vida
{"rel": "confirm-email", "href": "/users/10/confirm-email"}
]
}
- Layered system – cada camada ignora a próxima, estilo gestão corporativa.
- Code on demand – se der errado, culpe o client.
Resources (ou o que você provavelmente entendeu errado)
Tudo no REST gira em torno dos Resources. Não confunda REST com CRUD, ou algum arquiteto mala vai te explicar em detalhes porque você está errado.
The key abstraction of information in REST is a resource. — Roy Fielding, CHAPTER 5 - Representational State Transfer (REST)
Conclusão
REST é simples, desde que você não resolva ser criativo demais. Entenda Resources e pare de complicar o que é fácil.
Nos próximos posts vamos ver boas práticas reais, e eu espero sinceramente que você pare de chamar API bagunçada de REST.
Fale conosco