Conteúdo original em https://x.com/zanfranceschi/status/1797835707962245352

Ei dev,

Bora falar um pouco de semântica HTTP e porque acho FEIO retornar um 404 numa busca sem resultados?

No HTTP, uma imagem, uma folha de estilos, um arquivo javascript e detalhes de um usuário em formato JSON são todos igualmente considerados RECURSOS. TUDO É RECURSO!

🧵

E como TUDO É UM RECURSO, um endpoint de busca também é um recurso por si só!

Vamos supor os seguintes endpoints:

GET /users/:id - retorna detalhes de um usuário.
GET /users?q=:termo - retorna o resultado duma busca.

Dado que todos nós concordamos que GET /users é um recurso (certo?), o CONTEÚDO desse recurso, que é o resultado duma busca, por exemplo, pode ou não conter informações em formato de lista sobre usuários com atributos que se assemelham ao termo usado na query string 'q'.

O retorno de GET /users?=berto poderia ser algo como:

[{"nome": "Roberto"}, {"nome": "Adalberto"}]

E uma chamada para o mesmo recurso de busca com parâmetros diferentes – GET /users?=jubis – poderia retornar algo como:

[]

...uma lista vazia.

GET /users é um recurso – sempre!

404 é considerado um erro de quem chama seu servidor informando um recurso inexistente! O recurso de busca tá lá, o que não tá é o usuário com o nome Jubiscleiton que você colocou no parâmetro de busca. Faz sentido?

Se você é (era?) do time 404, espero ter te convencido de que uma busca é um recurso por si só.

Agora vou falar com você que é do time 204. Fica junto, cola na grade.

"Ain, mas não tem resultado, então não tem conteúdo, então é 204" ouço você resmungar. Rola pra baixo. ↓

SEMANTICAMENTE, a gente usa 204 pra quando estamos cagando para o (não) conteúdo.

Por exemplo, quando você manda um PUT /users/1, foda-se o corpo porque você sabe o novo estado do recurso. Tudo que importa é um retorno HTTP com status 204 dizendo que sua requisição deu certo. 👍

E num recurso que retorna, p.ex., uma lista (vazia ou não), você se importa com o corpo. É muito mais uniforme verificar o tamanho da lista do resultado da busca, por exemplo. Do contrário, você teria que verificar o status code pra ver se tem itens na lista. ↓

if vote 200t
then prinltn(data)
else if vote 204t
then "sem resultados"

🙄

Pra finalizar, uma singela homenagem ao @leandronsp:

Poesia "Pelo Reconhecimento da Busca Como um Recurso" by Zan:

GET /users/:id é a comida
GET /users?q=:termo é o pote
E o pote vazio
Não deixa de ser um pote

Mais uma coisa: se você tá mexendo num legado que retorna 404 ou 204 pra uma busca vazia e simplesmente não existe benefício em mudar isso, não sofra. O que importa em primeiro lugar é funcionar – seja com 404 ou 204, sinceramente.

Muito obrigado se chegou até aqui.

E não esqueça de deixar seu like, se inscrever no canal, e ativar o sininho pra você não vídeo novo do canal.

😗