Descomplicando o REST

"REST não é uma tecnologia, é um conjunto de restrições que ajudam a construir sistemas previsíveis. Quando essas restrições são violadas, a complexidade explode."

---

O problema: APIs que crescem sem direção

Muitos serviços começam como um pequeno conjunto de endpoints ad‑hoc. Cada nova funcionalidade traz um novo caminho, parâmetros confusos e respostas misturadas entre JSON e XML. Quando o número de consumidores aumenta – front‑ends mobile, parceiros B2B, pipelines de dados – a falta de um modelo consistente gera:

1. Dificuldade de documentação – sem convenções claras, cada cliente precisa descobrir por conta própria como usar o endpoint.
2. Inconsistência de estado – alguns recursos são atualizados via POST, outros via PATCH; a semântica de idempotência se perde.
3. Problemas de escala – rotas monolíticas impedem a distribuição de carga e a aplicação de políticas de cache adequadas.

Esses sintomas são sintomáticos de um design que ignora as restrições fundamentais do REST.

---

A solução: aplicar as restrições REST de forma consciente

1. Modelagem de recursos

• Identidade única – cada entidade deve ter um URI estável (/usuarios/{id}).
• Coleções vs. itens – use /usuarios para a coleção e /usuarios/{id} para um item. Sub‑recursos (/usuarios/{id}/enderecos) permitem navegação hierárquica sem criar verbos na URL.
• Nomes, não verbos – a URL descreve o que e não o que fazer.

2. Verbos HTTP corretos

Verbo	Semântica	Idempotente?
GET	Leitura segura, sem efeitos colaterais	Sim
POST	Criação de um recurso ou ação não‑idempotente	Não
PUT	Substituição completa de um recurso	Sim
PATCH	Atualização parcial	Não (mas pode ser tratado como idempotente se o payload for determinístico)
DELETE	Remoção de recurso	Sim

3. Códigos de status claros

• 2xx – sucesso (ex.: 200 OK, 201 Created, 204 No Content).
• 3xx – redirecionamento; útil quando recursos são versionados (/v1/usuarios → /v2/usuarios).
• 4xx – erro do cliente (ex.: 400 Bad Request, 401 Unauthorized, 404 Not Found).
• 5xx – falha do servidor; indica que o cliente pode tentar novamente.

4. Formato de resposta padrão

JSON domina por sua integração direta com JavaScript e bibliotecas de serialização. Quando houver necessidade de XML (ex.: integração com sistemas legados do governo brasileiro), ofereça content‑negotiation via cabeçalho Accept.

---

Implicações de escalabilidade

Distribuição de carga

Ao separar recursos em coleções distintas, você pode colocar cada coleção atrás de um load balancer especializado. Por exemplo, /pagamentos pode ser roteado para um cluster de micro‑serviços de alta taxa de transação, enquanto /relatorios vai para um serviço de processamento batch.

Cache HTTP

GET é cache‑ável por definição. Defina cabeçalhos Cache-Control, ETag e Last-Modified para que CDNs ou proxies de borda sirvam respostas sem tocar no backend. Isso reduz a latência e a carga de leitura em bancos de dados.

Sharding de dados

Se o recurso tem alta cardinalidade (ex.: milhões de usuários), use o identificador (/usuarios/{id}) como chave de partição. Sistemas como Cassandra ou CockroachDB permitem sharding automático baseado no ID, garantindo que a maioria das leituras vá direto ao nó responsável.

---

Modelos de consistência

REST não impõe um modelo de consistência, mas a escolha impacta a experiência do cliente.

Modelo	Características	Quando usar
Consistência forte	Operações de escrita são visíveis imediatamente após o retorno da chamada.	Transações financeiras, controle de estoque.
Consistência eventual	Escritas são propagadas assíncronamente; leituras podem retornar estado antigo por um curto período.	Feed de notícias, recomendações, analytics.

Implementar consistência forte geralmente requer two‑phase commit ou distributed transactions, que reduzem a disponibilidade (CAP). Consistência eventual permite alta disponibilidade e latência menor, mas exige que o cliente lide com versões desatualizadas (por exemplo, usando ETag para detectar mudanças).

---

Padrões de design de API RESTful

1. Versionamento via URI

/v1/usuarios → /v2/usuarios. Mantém compatibilidade retroativa e permite migração gradual.

2. HATEOAS (Hypermedia as the Engine of Application State)

Inclua links nas respostas (_links) para que o cliente descubra as próximas ações possíveis. Embora raramente usado em APIs públicas, ele garante que mudanças de rota não quebrem clientes que seguem os links.

3. Rate limiting e cabeçalhos de controle

Retorne 429 Too Many Requests com cabeçalhos Retry-After. Isso protege o backend de sobrecarga e fornece feedback claro ao consumidor.

4. Operações não‑CRUD como sub‑recursos ou parâmetros de ação

• Sub‑recurso: POST /livros/{id}/promocao cria uma promoção para o livro.
• Query param: GET /livros?tipo=promocao&categoria=autoajuda filtra recursos sem criar verbos.

---

Trade‑offs a considerar

Decisão	Benefício	Custo
Usar PATCH ao invés de PUT para atualizações parciais	Menor payload, menos risco de sobrescrever campos não enviados.	Necessita lógica de merge no servidor; pode complicar validações.
Expor recursos como sub‑recursos profundos (/livros/123/autores/456/endereco)	URL expressiva, hierarquia clara.	Pode gerar rotas muito específicas que dificultam versionamento e cache.
Cache agressivo (Cache-Control: max‑age=86400)	Redução drástica de carga de leitura.	Dados podem ficar desatualizados; requer invalidação via PURGE ou versionamento de URI.
Consistência forte com transações distribuídas	Garantia de integridade de dados.	Latência maior, menor disponibilidade, maior complexidade operacional.
Versionamento via header (Accept: application/vnd.myapi.v2+json)	URLs permanecem limpas; clientes escolhem versão explicitamente.	Mais difícil de depurar; ferramentas de documentação precisam suportar múltiplos media types.

---

Conclusão prática

1. Comece com recursos bem definidos – pense em termos de entidades de domínio, não de operações.
2. Aplique verbos HTTP corretamente – isso traz idempotência natural e simplifica o cache.
3. Escolha o modelo de consistência que o negócio exige – não há motivo para pagar o preço da consistência forte se a aplicação tolera eventual.
4. Implemente versionamento e limites de taxa desde o início – evita dor de cabeça quando a base de consumidores crescer.
5. Documente tudo – use OpenAPI/Swagger para gerar contratos claros; inclua exemplos de códigos de status e cabeçalhos de cache.

Seguindo essas diretrizes, sua API REST permanecerá compreensível, escalável e resiliente, mesmo quando o número de usuários e serviços integrados disparar.

---

Referências

• RESTful API Design – Microsoft Docs
• OpenAPI Specification
• CAP Theorem Explained