404, 204, 200? Qual status a API deve retornar quando a resposta for vazia?
No dia a dia de trabalho sempre me deparo com códigos e definições que me fazem refletir se aquela é a forma correta ou se é a melhor forma para resolver o problema. Para muitos casos é fácil pesquisar e encontrar o padrão recomendado, mas para outros pode não ser tão fácil encontrar uma recomendação ou uma definição de como deve ser feito.
Resolvi fazer algumas postagens aqui para trazer um pouco do meu conhecimento e minhas impressões sobre alguns conceitos dentro do desenvolvimento de API. Para esse primeiro post vamos falar sobre os códigos de status que geram dúvidas e quando usá-los.
Muitas das coisas que vou trazer são muito bem definidas nos RFC (Request for Comments). RFC são documentos usados pela comunidade online há mais de 40 anos para definir os padrões da web e compartilhar informações técnicas. Atualmente, os RFCs são gerenciados pela IETF (Internet Engineering Task Force).
Vamos lá!
Imagine que temos um endpoint GET /cliente/{idCliente}, ao fazer a requisição GET /cliente/2433 esperamos obter os dados do cliente com identificador 2433, mas e se esse cliente não existir na base de dados? O que o endpoint deveria retornar? Para esse caso os status de retorno mais comuns de se encontrar são: 204 (No Content) e 404 (Not Found).
A princípio o retorno No Content pode parecer fazer sentido, mas o correto nessa situação é retornar 404 (Not Found) por que estamos falando de um recurso (Uniform Resource Locator, lembra?) e quando um recurso não existe o correto é que o status de retorno seja 404. Isso fica muito claro quando lemos o RFC7231.
O código de status 404 (não encontrado) indica que o servidor de origem não encontrou uma representação atual para o recurso de destino ou não está
disposto a divulgar que existe.
Agora vamos imaginar que temos o endpoint GET /cliente?nome=Leandro. A primeira coisa que vemos é que se trata de uma busca na base de clientes pelos registros com nome Leandro. E se não existirem registros, qual deve ser o status de retorno? 404 como no exemplo anterior?
Nesse caso ao pesquisarmos no Google vemos vários tipos de recomendações de qual status deve ser usado no retorno.
O RFC7230 diz que o range de status entre os códigos 400 e 500 devem ser usados para mensagens de erro.
Os endpoints da API devem ter retornos claros e coerentes para que não gere dúvidas nos consumidores do serviço. Então, para esse exemplo podemos retornar um status 200 (Success) com o body contendo uma lista vazia. Assim o nosso consumidor não terá dúvidas quanto a resposta da API.
O body pode ser como esse:
HTTP/1.1 200 OK
Content-Type: application/json
{
"total": 0,
"clientes": [],
"query": {
"nome": "Leandro"
}
}E quando devemos usar o 204?
Quando a resposta da requisição não exigir um resultado, em caso de um UPDATE por exemplo.
O usuário Woss, do StackOverflow, fez uma ótima analogia para exemplificar como o retorno do UPDATE deve ser.
Imagine que você precisa solicitar ao estagiário que ele mude a posição da cafeteira no escritório. Hoje ela fica na cozinha, mas você quer que ela seja instalada na sua mesa. Você pode chegar pro estagiário e pedir “Saudações terráqueo, por favor, mude a posição da cafeteira. Traga ela da cozinha para a minha mesa”. O estagiário, eficiente como sempre, prontamente faz a mudança e a fim de te informar que a tarefa foi executada ele chega até você e responde uma das opções abaixo:
Pronto!
Pronto, mudei a cafeteira de lugar. Agora ela está instalada na sua mesa.
Em seguida ele questiona, concorda que as duas opções são completas?
Ou seja, a API retornar apenas um 204, que diz “Ei eu recebi a sua solicitação e deu tudo certo”, fica claro para o consumidor que não há necessidade de um body da resposta.
Esses são os status que mais vejo divergências na implementação ao olhar códigos de outros programadores ou pesquisando na internet. O mais importante em relação aos retornos da sua API é que eles sejam coerentes, que não confundam o consumidor exibindo tipo de retornos diferentes para requisições semelhantes.
Bibliografia:
