Eu estava dando uma consultoria para uma empresa, enquanto estava na África do Sul, e nós fizemos um acordo. Você aciona a funcionalidade SOAP para mim e eu escrevo endpoints RESTful. Essa foi a criação da API de disparo rápido com 20 pessoas na sala.

Foi divertido, mas algumas coisas foram complicadas. As necessidades da companhia estavam longe de ser triviais, sendo uma empresa que envia milhões de e-mails e mensagens de texto por dia para pessoas com vários tipos diferentes de número de telefone, short-code ou ID do usuário. Uma ou duas vezes me vi sugerindo alguns endpoints espertos que não eram RESTful, mas toda vez que isso acontecia, eu forçava meu cérebro a trabalhar um pouco mais firme para descobrir quais combinações iriam satisfazer os deuses RESTful e, assim, evitar que despejassem sua ira sobre mim.

Estilo SOAP

Tradicionalmente APIs consistiriam em uma série de endpoints que descreveram verbos (ações):

POST /SendUserMessage HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
id=5&message=Hello!

Como você já deve ter percebido, não é assim que as coisas são feitas com REST.

Meio RESTful

Alguns desenvolvedores de API consideram a seguinte abordagem para ser mais RESTful, pois será usado um “sub-recurso”:

POST /users/5/send-message HTTP/1.1
Host: example.com
Content-Type: application/json
{ “message” : “Hello!” }

Não, porque isso ainda está usando um verbo na URL. Um verbo é uma ação – um termo que faz, e nossa API só precisa de um verbo – o método HTTP. Todos os outros verbos precisam ficar de fora da URL.

Um substantivo é um “lugar” ou uma “coisa”. Os recursos são “coisas”, e uma URL torna-se o “lugar” na Internet, onde uma “coisa” mora.

RESTful de fato

Este exemplo seria drasticamente mais RESTful:

POST /users/5/messages HTTP/1.1
Host: example.com
Content-Type: application/json
{ “message” : “Hello!” }

Perfeito! Estamos criando uma nova mensagem, que pertence a um usuário. A melhor parte de mantê-lo agradável e RESTful assim é que outras ações HTTP podem ser feitas para uma URL idêntica:

• GET /users/philsturgeon/messages
• PATCH /users/philsturgeon/messages/xdWRwerG
• DELETE /users/philsturgeon/messages/xdWRwerG

Isso tudo é muito mais fácil para se documentar e entender tanto por humanos quanto por softwares que são clientes RESTful.

Portanto, para esse cliente, eles tiveram que enviar potenciais de centenas de milhares de mensagens em uma base regular. A solução que achamos foi tornar /messages seu próprio endpoint e enviar as mensagens em lotes de algumas centenas:

POST /messages HTTP/1.1 Host: example.com Content-Type: application/json
{ [{ “user” : { “id” : 10 }, “message” : “Hello!” },
{ “user” : { “username” : “philsturgeon” }, “message” : “Hello!” }] }

Isso ficaria incrivelmente semelhante para criar os dados como para obtê-los, o que é intencional. Independentemente do verbo HTTP e da URL específica, uma pá deve sempre parecer com uma pá, e um saco de chaves de boca deve sempre parecer como um saco de chaves de boca. As coisas devem ter um padrão específico e não devem exigir suposições para descobrir como as coisas se parecem para GET ou POST … a menos que você esteja no Facebook e aí é apenas um grande gameshow sem prêmios.

***

Artigo traduzido pela Redação iMasters com autorização do autor. Publicado originalmente em https://philsturgeon.uk/rest/2014/05/11/restful-urls-actions-need-not-apply/