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/

Deixe uma resposta

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

Post Navigation