Será que RESTFul é um nome bonito para CRUD?

Te disseram que API's RESTFul utilizam substantivos ao invés de verbos? Coisas ao invés de ações? Pois é, mais uma meia-verdade vendida como mantra sagrado de arquitetura. Bora ver como uma definição meia-boca pode transformar um sistema bem desenhado numa salada de endpoints sem propósito.

Ah, os verbos HTTP. Aqueles quatro cavaleiros do CRUD-pocalipse:

• Create → POST
• Read → GET
• Update → PUT / PATCH
• Delete → DELETE

E é aí que começa a festa. Misturam REST com CRUD como se fossem irmãos siameses. E nessa lambança, quem tenta fazer um design decente de API RESTFul acaba se engasgando com as próprias URLs.

Resources

O senso comum, aquele que nunca leu uma linha do Fielding, adora simplificar:

• Coisa ao invés de ação
• Substantivos ao invés de verbos

Aí vem aquele exemplo batido que aparece em todo blog ou workshop sobre "como fazer uma API bonitinha":

POST /users            # Cria um usuário
PUT /users/{id}        # Atualiza o usuário inteiro
PATCH /users/{id}      # Atualiza parcialmente o usuário
DELETE /users/{id}     # Remove o usuário

Sim, lindo, limpinho e cheiroso. Parece até que foi gerado por IA. Mas e quando o mundo real bate na sua porta com requisições que não cabem numa caixinha de CRUD?

O negócio começa a feder quando seu recurso tem comportamentos. E sim, eu disse comportamentos, porque se você acha que tudo se resolve com PUT e PATCH, prepare-se para chorar sangue em APIs de verdade.

Veja o caso abaixo, um clássico:

POST /candidatos/{id}/submit      # Submete o candidato para análise
POST /candidatos/{id}/approve     # Aprova o candidato
POST /candidatos/{id}/decline     # Recusa o candidato
POST /candidatos/{id}/transfer    # Transfere o candidato para outro processo

Aqui o recurso candidatos tá se comportando como um objeto com responsabilidades. approve pode disparar eventos, notificar o RH, acender a luz da cafeteira... sei lá. É um comportamento.

E não, REST nunca disse que isso não pode. Quem disse foi algum indiano que disseminou o Caos e depois os dev influencer espalhou pra ganhar like.

REST é sobre Resource

O tio Fielding, na sua bíblia arquitetural, não disse que resource precisa ser um substantivo inofensivo que não morde.

Ele falou que resource é qualquer coisa que possa ser identificada. Qualquer coisa, meu chapa. Uma ação? Pode. Um relatório? Pode. O cheiro da janta da sua API? Se der pra identificar com URI, pode também.

A RFC 3986 confirma:

"Resource" é qualquer coisa que possa ser identificada por uma URI.

E aí, onde entra a sua açãozinha?

/candidatos/{id}/approve é um recurso. Tem URI. Tem semântica. E adivinha? Está dentro do REST.

Dicas e sugestões

Não tem um santo evangelho oficial de boas práticas para APIs REST. O que tem é bom senso e experiência de mercado. Ou seja, tudo que meia dúzia de desenvolvedor júnior acha que pode ignorar porque viu um vídeo no YouTube.

1. Use os verbos HTTP direito.

Antes de inventar um endpoint do tipo POST /usuarios/criar, lembre-se: já temos o verbo no protocolo. Basta POST /usuarios. Criar o verbo de novo na URL é como colocar um return true; depois de exit().

Agora, se o seu cenário tem regra de negócio, tipo POST /usuarios/2/solicitar-ferias, vá em frente. Isso é comportamento. Pode usar com CQRS, com Command Handler, com o que fizer sentido. Só não seja refém de dogma mal explicado.

Com isso, seu time pode parar de desenhar APIs que parecem formulários de cadastro de 2004 e começar a pensar em design de verdade.

Conclusão

REST é um conceito. Um bom conceito. Mas como tudo em TI, se mal interpretado, vira religião de slide de PowerPoint. A galera se prende a "tem que ser substantivo" e esquece que API é sobre expressar comportamentos e regras do domínio.

Quer fazer REST direito? Estuda o conceito de resource. Depois volta e olha sua API de novo.

Referências

• Architectural Styles and the Design of Network-based Software Architectures
• REST Api - Enchant
• Uniform Resource Identifier (URI): Generic Syntax - RFC 3986