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 DELETEMas 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/

6 Thoughts on “API GET: Sem conteúdo: 404 vs 204 vs 200

  1. 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

  2. João Paulo Gomes on 20/09/2020 at 10:10 said:

    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.

Deixe uma resposta

Esse site utiliza o Akismet para reduzir spam. Aprenda como seus dados de comentários são processados.

Post Navigation