No cenário atual de infraestrutura e desenvolvimento, a eficiência de uma empresa não reside apenas na robustez de seus servidores ou na qualidade de seu código isolado, mas sim na fluidez com que seus sistemas conversam. Como Google Premier Partners, na NetExperts, lidamos diariamente com arquiteturas complexas onde a comunicação entre microsserviços e APIs é o coração da operação.Hoje, exploraremos a evolução da comunicação via REST (Representational State Transfer), utilizando o Modelo de Maturidade de Richardson para entender como transformar simples trocas de dados em sistemas verdadeiramente inteligentes e auto descritivos.
O Que é o Modelo de Maturidade de Richardson?
Desenvolvido por Leonard Richardson, este modelo divide a implementação de APIs REST em quatro níveis (do 0 ao 3). Quanto mais alto o nível, mais o sistema adere aos princípios da Web, garantindo escalabilidade e facilidade de manutenção.
Nível 0: O Pântano do POX (Plain Old XML)
Neste estágio inicial, não há padrão real. O protocolo HTTP é usado apenas como um túnel de transporte. As rotas parecem funções (estilo RPC – Remote Procedure Call), o que é comum em protocolos como gRPC ou SOAP, mas inadequado para o REST puro.
- Exemplo: POST /getCliente ou POST /salvarDados.
- Problema: O verbo HTTP não importa; tudo costuma ser enviado via POST, e a URL descreve uma ação, não um recurso.
Nível 1: Recursos
Aqui, começamos a organizar a API em torno de Recursos (substantivos) em vez de ações (verbos). Cada entidade (como um cliente ou pedido) ganha sua própria URI.
- Exemplo: /clientes/123 ou /pedidos.
- Avanço: O sistema já entende a diferença entre os objetos, mas ainda costuma falhar no uso correto dos métodos HTTP.
Nível 2: Verbos HTTP (A Forma Verbosa e Correta)
Este é o nível onde a maioria das boas APIs de mercado se encontra. Aqui, utilizamos o protocolo HTTP em sua plenitude técnica. Em vez de colocar a ação na URL, usamos o método apropriado para indicar a intenção.
- GET: Recuperar dados.
- POST: Criar novos registros.
- PUT/PATCH: Atualizar dados.
- DELETE: Remover registros.
Exemplo Prático de Requisição Nível 2:
HTTP
POST /produtos
{ “nome”: “Servidor Cloud vCPU 4”, “preco”: 500.00 }
O servidor responde com 201 Created em caso de sucesso, utilizando os Status Codes de forma semântica.
Nível 3: HATEOAS (O Estado do RESTful)
Chegamos ao topo da maturidade. Uma API só é considerada RESTful de fato quando implementa o conceito de HATEOAS (Hypermedia as the Engine of Application State).
Neste nível, o endpoint não entrega apenas os dados, mas também informa ao cliente o que ele pode fazer a seguir. É como um menu dinâmico: se você busca um pedido, a resposta já traz os links para cancelar o pedido, pagar ou verificar o rastreio.
Exemplo de Resposta RESTful:
JSON
{
“id”: 1020,
“status”: “aguardando_pagamento”,
“valor”: 1200.00,
“links”: [
{ “rel”: “self”, “href”: “/pedidos/1020” },
{ “rel”: “pagar”, “href”: “/pedidos/1020/checkout” },
{ “rel”: “cancelar”, “href”: “/pedidos/1020/cancel” }
]
}
Tutorial: Construindo uma Rota Semântica com Node.js e Express
Para implementar a maturidade nível 2 e 3, sua estrutura de código deve respeitar a semântica dos recursos.
- Defina o Recurso: Vamos usar servidores.
- Use Verbos Corretos:
JavaScript
const express = require(‘express’);
const app = express();
app.use(express.json());
// Banco de dados simulado
let servidores = [{ id: 1, nome: “Mainframe-01”, status: “ativo” }];
// NÍVEL 2: Rota para buscar um recurso específico
app.get(‘/servidores/:id’, (req, res) => {
const servidor = servidores.find(s => s.id === parseInt(req.params.id));
if (!servidor) {
// Observação importante: 404 para recurso específico não encontrado
return res.status(404).json({ erro: “Servidor não encontrado” });
}
// NÍVEL 3: Adicionando HATEOAS (links de ação)
res.json({
…servidor,
_links: [
{ rel: “update”, method: “PUT”, href: `/servidores/${servidor.id}` },
{ rel: “delete”, method: “DELETE”, href: `/servidores/${servidor.id}` }
]
});
});
app.listen(3000, () => console.log(“API NetExperts rodando na porta 3000”));
Observação Técnica: 200 vs 404 (A Confusão Comum)
Um erro frequente em integrações de TI é o tratamento incorreto de retornos vazios. Na NetExperts, seguimos o padrão rigoroso da W3C:
- Busca por ID (/clientes/123): Se o ID específico não existe no banco, o retorno deve ser 404 Not Found. Você buscou algo específico que não existe.
- Busca Geral ou Filtro (/clientes?nome=gabriel): Se a busca não retornar nenhum resultado, o retorno deve ser 200 OK, porém com uma lista vazia []. Isso indica que a rota existe, a consulta foi válida, mas não há dados que correspondam ao critério no momento.
Conclusão
A adoção do padrão RESTful não é apenas uma escolha estética, mas uma estratégia para reduzir o acoplamento entre sistemas e facilitar o Outsourcing e a escalabilidade em nuvem. Ao elevar o nível de maturidade de suas APIs, você garante que sua infraestrutura esteja pronta para o futuro.
Referências e Documentações Oficiais:
- Richardson Maturity Model – Martin Fowler
- HTTP Status Codes – MDN Web Docs
- Documentação Oficial do gRPC (Comparativo RPC vs REST)
- Melhores Práticas para Design de API REST – Google Cloud
