Será que RESTFul não passa de um nome mais chique pra CRUD? É tipo colocar perfume francês num porco e achar que virou inovação. E aquela história de que “API RESTFul usa substantivos ao invés de verbos”? Ah, claro… porque trocar “fazerCoisa” por “coisa” vai magicamente salvar a arquitetura do seu sistema. Spoiler: não vai.
Esse tipo de meia-verdade mal formulada já detonou o design de milhares de times. Mas tudo bem, segue o baile: cada equipe criando sua própria religião de endpoints, como se o mundo fosse se acabar se alguém ousar usar um verbo no caminho da URL.
Todo mundo já viu aquela tabelinha que casa CRUD com os verbos HTTP:
- Create → POST
- Read → GET
- Update → PUT / PATCH
- Delete → DELETE
É útil para começar? Sim. Mas achar que REST se resume a isso é como acreditar que “programar é só fazer if e for”. Simplifica demais e, no fim, atrapalha.
Resources
Grande parte da confusão vem da tal definição de Resource. Aí surge o mantra: “Resource deve ser substantivo, nunca verbo. Sempre coisa, nunca ação”. Parece bonito, mas esse absolutismo cria mais problemas do que resolve.
Veja esse exemplo clássico:
POST /users # Cria um usuário
PUT /users/{id} # Atualiza o usuário
PATCH /users/{id} # Atualiza parcialmente
DELETE /users/{id} # Remove o usuário
Está certinho: usa bem os verbos HTTP, resources como substantivos… mas é só o cenário de manual. Na prática, o dia a dia é bem mais complexo. Os objetos do sistema não são estáticos, eles têm comportamentos, regras, transições.
Um candidato, por exemplo, não é apenas criado ou atualizado. Ele pode ser submetido, aprovado, recusado, transferido… e cada ação dispara consequências diferentes, desde eventos para outros sistemas até fluxos de aprovação.
POST /candidatos/{id}/submit
POST /candidatos/{id}/approve
POST /candidatos/{id}/decline
POST /candidatos/{id}/transfer
Sim, aqui aparecem verbos no caminho. E não, isso não quebra o REST. O problema é quando transformamos regras de bom senso em dogmas religiosos. REST nunca limitou recursos a substantivos estáticos sem comportamento. Essa leitura simplista é que acabou virando uma armadilha para muitos times.
REST é sobre Resource
Muita gente repete por aí que “Resource tem que ser substantivo”, como se estivesse gravado em pedra. Mas o artigo do Roy Fielding nunca disse isso. Na verdade, ele afirma justamente o contrário: um Resource é qualquer coisa que possa ser identificada.
A RFC 3986 reforça essa visão. Recurso é o que puder ser identificado por uma URI. E os exemplos vão muito além de “usuários” e “produtos”:
This specification does not limit the scope of what might be a resource; rather, the term "resource" is used in a general sense for whatever might be identified by a URI. Familiar examples include an electronic document, an image, a source of information with a consistent purpose (e.g., "today's weather report for Los Angeles"), a service (e.g., an HTTP-to-SMS gateway), and a collection of other resources. Uniform Resource Identifier (URI): Generic Syntax - RFC 3986
Ou seja: não há essa limitação artificial de “sempre substantivo, nunca ação”. Uma ação também pode ser identificada, e portanto, também pode ser um resource válido.
Um endpoint como candidato/{id}/approve é perfeitamente legítimo:
- Ele é único,
- Ele é identificável,
- Ele tem uma URI clara.
E o melhor: a própria URL já comunica a intenção. Você combina isso com os verbos HTTP e pronto, fica explícito o que está acontecendo. Não é invenção, não é gambiarra, é simplesmente usar o conceito como ele foi definido, e não como foi simplificado em tutoriais de PowerPoint.
Dicas e sugestões
Não existe um “guia oficial” das melhores práticas para projetar APIs REST. O que temos é um conjunto de consensos que, na prática, evitam que cada time reinvente a roda do jeito mais torto possível. Então, vamos ao básico.
1. Respeite os verbos HTTP. Antes de sair inventando moda, entenda a semântica do protocolo.
| HTTP Method | Seguro | Semântica |
|---|---|---|
| OPTIONS | Sim | Retorna os métodos HTTP válidos e outras opções |
| GET | Sim | Busca um resource |
| HEAD | Sim | Busca apenas o header de um resource |
| PUT | Não | Atualiza um resource |
| POST | Não | Cria um resource |
| DELETE | Não | Remove um resource |
| PATCH | Não | Atualiza parcialmente um resource |
Parece óbvio? Pois é. Mas sempre tem alguém que acha uma boa ideia criar endpoints como POST /usuarios/criar. Não, não é. O verbo HTTP já carrega essa semântica. O correto seria simplesmente POST /usuarios.
Agora, se for um comportamento específico de negócio, aí sim faz sentido expor a ação:
POST /usuarios/2/solicitar-ferias
Aqui não estamos duplicando o papel do verbo HTTP, mas deixando claro um requisito de negócio. É nesse ponto que entra o CQRS: a controller pode esperar algo como SolicitarFeriasCommand, dando clareza ao design.
E o que o time ganha com isso? Liberdade. Ao parar de pensar em REST apenas como CRUD, você pode modelar APIs mais expressivas, que refletem o domínio do sistema, sem trair os princípios do REST. E o bônus: menos endpoints esquisitos inventados às pressas.
Conclusão
O REST já é um conceito bem estabelecido no mercado. O problema é que a falta de entendimento sobre o que realmente é um Resource faz muitos times desperdiçarem horas preciosas em discussões intermináveis, tudo para decidir se uma URL “quebra” ou não o sagrado padrão RESTFul.
Spoiler: na maioria das vezes, o problema não é o REST, é a interpretação literal demais.
Se este texto ajudou você a enxergar que REST não é só CRUD enfeitado e que um resource pode sim refletir comportamentos do negócio, missão cumprida.
E se não ajudou… bom, pelo menos você já sabe que POST /usuarios/criar continua sendo um cheiro ruim de design.
Fale conosco