Qual é a resposta HTTP que sua API REST deve retornar quando o recurso solicitado não existe.
Por exemplo, considere a seguinte API para buscar um funcionário.
GET http://yourservice.com/api/v1/employees/1
Response Header: 200
Body: {
"name":"Santhosh",
"department":"Engineering"
}Quando o empregado solicitado não existe
GET http://yourservice.com/api/v1/employees/2
Response Header: ???
Body: ???Existem três escolhas; 404, 204 e 200. Todos os três parecem adequados para o caso de uso. Vamos examiná-los detalhadamente com o objetivo de escolher o melhor.
Vamos começar com:
404 não encontrado
De acordo com a definição do código de status HTTP…
“O servidor não encontrou nada que corresponda ao URI de solicitação. Nenhuma indicação é dada se a condição é temporária ou permanente. O código de status 410 (Gone) DEVE ser usado se o servidor souber, por meio de algum mecanismo configurável internamente, que um recurso antigo está permanentemente indisponível e não possui endereço de encaminhamento. Esse código de status é comumente usado quando o servidor não deseja revelar exatamente por que a solicitação foi recusada ou quando nenhuma outra resposta é aplicável. ”
A primeira declaração faz todo o sentido para o caso. No entanto, quando você lê adiante, fica claro que 404 não é a escolha certa por causa das razões a seguir
- O código é usado quando o recurso não está permanentemente disponível, o que não é o caso aqui.
- O servidor não deseja ocultar o motivo exato.
- Há uma terceira razão para não usar o 404; a série 4xx destina-se a sinalizar erros do cliente. Mas um recurso restante não disponível não é um erro. É um estado temporário.
Ambos os candidatos restantes pertencem à categoria 2xx.
“Esta classe de código de status indica que a solicitação do cliente foi recebida, entendida e aceita com sucesso.”
Sim! isso faz sentido para o caso dado. Então, um desses códigos de erro deve ser uma escolha melhor em comparação com 404. Vamos começar com os menos familiares …
204 Nenhum conteúdo
De acordo com a definição do código de status HTTP…
O servidor cumpriu a solicitação, mas não precisa retornar um corpo de entidade e pode querer retornar meta informações atualizadas. A resposta pode incluir meta informações novas ou atualizadas na forma de entidade-cabeçalhos, que se presentes devem ser associados com a variante solicitada.
Se o cliente for um agente do usuário, NÃO DEVE alterar sua visão do documento daquela que fez com que a solicitação fosse enviada. Essa resposta destina-se principalmente a permitir que a entrada de ações ocorra sem causar uma alteração na visualização do documento ativo do agente do usuário, embora quaisquer meta-informações novas ou atualizadas DEVEM ser aplicadas ao documento atualmente na visualização ativa do agente do usuário.
A resposta 204 NÃO DEVE incluir um corpo de mensagem e, portanto, é sempre terminada pela primeira linha vazia após os campos de cabeçalho.
204 parece o candidato certo, porque a sua forma resumida é “sem conteúdo”. No entanto, quando você estuda a definição, fica evidente, a partir da quarta declaração (texto em negrito), que 204 é ideal quando uma ação ocorre no servidor. ou seja, POST, PUT ou DELETE; Mas esse não é o caso quando o cliente invoca uma solicitação GET.
Ficamos com o mais comumente usado 200 OK
200 OK {com corpo vazio}
Conforme a definição do código de status HTTP
O pedido foi bem sucedido. As informações retornadas com a resposta dependem do método usado na solicitação, por exemplo:
GET uma entidade correspondente ao recurso solicitado é enviada na resposta; …
Quando o servidor retorna 200 com um corpo vazio, ele pode ser interpretado como “a solicitação é processada com sucesso, mas o recurso está vazio”. Embora não haja violação dos padrões HTTP, parece um pouco hacky. No entanto, considerando as outras opções, esta é uma opção muito melhor por causa dos seguintes motivos.
- É consistente com o comportamento geral do servidor.
- O código do cliente não precisa manipular outro código de resposta HTTP.
Conclusão
Quando uma solicitação da API REST GET não tem conteúdo, 200 com corpo vazio é a melhor opção de resposta.
GET http://yourservice.com/api/v1/employees/2
Response Header: 200
Body: {}Material de Apoio:
https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1
https://restfulapi.net/http-status-codes/
Achei bacana seu artigo, realmente é um ponto de discordância “épico”, mas um ponto que discordo é o uso do código 200 num caso onde buscamos por um id específico como no exemplo: http://yourservice.com/api/v1/employees/2 creio que nesta situação um 404 é o ideal. Já se estivermos fazendo uma consulta que gere uma lista, aí sim um retorno vazio encaixaria num 200.
Olá, realmente esse é um ponto “épico” de discordância..rs..
Obrigado pelo seu comentário.
Fabrizio Gianfratti
Também uso 404 em caso de URLs inválidas. Quando se passa um ID em uma URL e este ID não existe, o cliente errou a requisição, logo deve receber um 4xx (especificamente, 404). Eu diria que acessar uma URL direto com um ID é provavelmente resultado de uma tentativa e erro. Acessar direto os IDs deveria ser um passo depois de passar por um endpoint de pesquisa. O próprio ID deveria ser um UUID (humanamente sem significado) a ponto de impedir o “chute errado” e forçar sempre pela passagem de um endpoint de busca com dados legíveis como funcional, nome etc. Já quando se faz busca sem ID e com query-strings, caracteriza uma pesquisa e se não dá match, consequentemente traz o retorno vazio. Aí não é erro. é 200 vazio, como no artigo
Voltar 200 com corpo vazio vai dar um trabalho imenso para os consumidores da API, prefiro usar 204 ou 404 pois apenas lendo o status code o client já consegue saber que o recurso não existe.
Olá João, tudo bem ? Obrigado por comentar ”
É uma forma, vou deixar seu comentário como publico para contribuir seu ponto de vista como outras pessoas.
Abs,
Fabrizio Gianfratti
João, o trabalho não chega a ser imenso. Trabalho há alguns anos corporativamente em bancos de grande porte com esta a abordagem de corpo vazio como o Gianfratti falou. Mas também prefiro o 404 para falhas de IDs via URL (path parameter). No entanto, usar o 204 em GETs vai contra as especificações do HTTP e também convenção de uso no mercado (percebe-se pouca adoção). Quando se usa REST, infelizmente para se adequar às restrições desta abordagem arquitetural, devemos abrir mão de algumas praticidades. O RESTfull bem feito é um pouco mais “doloroso” pra implementar.