RESTFul é só um CRUD bonito?

Te disseram que APIs RESTFul usam substantivos no lugar de verbos? Coisas em vez de ações? Pois é, mais uma meia verdade dita como regra sagrada de arquitetura. Vamos ver como uma definição mal feita pode transformar um sistema bem projetado em uma bagunça de endpoints sem sentido.

Ah, os verbos HTTP. Aqueles quatro que representam o CRUD:

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

E é aí que a confusão começa. Misturam REST com CRUD como se fossem a mesma coisa. E nessa mistura, quem tenta fazer um design decente de API RESTFul acaba se complicando com as URLs.

Recursos

O pessoal, que nunca leu nada do Fielding, adora simplificar:

• Coisa em vez de ação
• Substantivos em vez de verbos

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

POST /users            # Cria um usuário
PUT /users/{id}        # Atualiza o usuário todo
PATCH /users/{id}      # Atualiza parte do usuário
DELETE /users/{id}     # Remove o usuário

Sim, arrumadinho. Mas e quando a realidade aparece com pedidos que não são só CRUD?

O problema aparece quando seu recurso tem ações. Sim, ações, porque se você acha que tudo se resolve com PUT e PATCH, prepare-se para desafios em APIs de verdade.

Olha este exemplo clássico:

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

Aqui, o recurso candidatos está agindo como um objeto com ações. approve pode acionar eventos, avisar o RH e mais. É uma ação.

E não, REST nunca disse que isso não pode. Quem disse foi alguém que não leu as especificações.

REST é sobre Recurso

O Fielding, na sua obra arquitetural, não disse que recursos precisam ser substantivos bobos.

Ele disse que recurso é qualquer coisa que possa ser identificada. Qualquer coisa. Uma ação? Pode. Um relatório? Pode.

A RFC 3986 confirma:

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

Então, onde entra a sua ação?

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

Dicas e sugestões

Não tem um manual oficial de boas práticas para APIs REST. O que tem é bom senso e experiência de mercado.

1. Use os verbos HTTP corretamente.

Antes de criar um endpoint como POST /usuarios/criar, lembre-se: já temos o verbo no protocolo. Basta POST /usuarios.

Agora, se a sua situação tem regra de negócio, tipo POST /usuarios/2/solicitar-ferias, vá em frente. É uma ação.

Com isso, seu time pode parar de criar APIs que parecem Formulários Web de 2004 e começar a pensar em um 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 agarra em "tem que ser substantivo" e esquece que API é sobre mostrar ações e regras do domínio.

Quer fazer REST direito? Estude o conceito de recurso. Depois volte e olhe 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