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.
😗
Top comments (6)
Olá tudo bem?
Achei interessante a proposta mas, gostaria de saber de forma mais simplista como se solucionaria ou exibiria ao usuário que determinado recurso não está disponível? Uma vez que erros de 404 são "clássicos" para informar que determinado recurso não existe e/ou está indisponível?
Ele não disse para não usar 404. Ele disse para só usar 404 quando um recurso não for encontrado.
Em uma busca, se ela não encontrar nada, retorne uma lista vazia pois a busca funcionou perfeitamente. Os termos da busca é que não encontraram nada.
Agora quando você tenta exibir os dados de um usuário pelo id, e esse usuário não existe, você está acessando um recurso inexistente, então é 404.
Boa! Obrigado pela resposta, Claudio!
Belo artigo Zan, mas agora eu me sinto estranho pq eu nunca cogitei usar 204 ou 404 como retorno de pesquisa que não retorna nada. Talvez o motivo seja pq eu não lembro de ter usado uma API que fazia isso, logo nunca tentei replicar o comportamento.
Muito interessante seu ponto de vista. Mas, discordo quando diz que um endpoint é um recurso. Quando se cria um endpoint (aqui vou pontuar métodos GET), temos uma URL (Uniform resource locator) ou URI (Uniform Resource Identifier), sendo assim, o acesso é para identificar um recurso, no caso de não encontrar, não acho estranho e nem ruim retornar um 404 no caso de não encontrar o que foi procurado, já no caso de uma lista vazia, o recurso foi encontrado porém está vazio, 204... Sempre segui por essa linha.
Acho válido, mas continuarei retornando 404 por compatibilidade e uma lista vazia quando for o caso.