Vou descrever um exemplo:
começo a fazer uma API para uma padaria. A API permitirá que as pessoas pesquisem em seu catálogo produtos de panificação, como biscoitos caseiros com pedaços de chocolate api.examplebakery.com/search?q=.....
.
Alguém usa isso para procurar um produto nomeado pineapple-banana flavoured cookies
e obviamente não encontrará nenhum resultado.
Isso deve ser retornado como um erro? A pesquisa não falhou, a API pesquisou e concluiu com êxito que nenhum cookie foi encontrado. A API não deve retornar 404
, porque a API foi realmente encontrada.
rest
http-response
Berry M.
fonte
fonte
Respostas:
Quando há resultados, a saída é uma lista (JSON, com base no seu comentário). Para consultas sem resultados, a saída deve ser exatamente a mesma. A lista simple possui 0 itens.
Portanto, se sua resposta é normalmente esta:
Então, para uma consulta com 0 resultados, deve ser o seguinte:
Se você também incluir metadados sobre quantas "páginas" de resultados existem, links para essas "páginas" etc. etc., sugiro dizer que existe uma "página".
O status HTTP deve ser o mesmo de quando houver resultados -
200 OK
.204 No Content
também pode parecer uma opção, mas não é porque você está retornando "conteúdo" - a lista vazia. Se você acha que uma lista vazia não conta como "conteúdo", e se você alterar a resposta para oferecer sugestões de ortografia? O núcleo da resposta ainda será uma lista vazia, mas agora há ainda mais "conteúdo".Para obter informações mais úteis sobre códigos de status HTTP, jpmc26 vale a pena ler sua resposta .
fonte
Ao decidir sobre um código HTTP, você deve sempre fazer esta pergunta:
Sempre decida em qual intervalo seu código de resposta deve estar primeiro. Fazer isso rapidamente elimina muitos códigos de resposta como opções e (talvez mais importante) torna muito mais simples seguir a semântica dos códigos. Consulte as seções iniciais da documentação do código HTTP para obter explicações sobre o que cada categoria de código representa.
Nesse caso, o cliente solicitou uma lista de resultados com um filtro de um terminal válido existente e tem autorização para acessá-lo. O servidor conseguiu processar a solicitação e determinar os dados apropriados a serem retornados (sem itens), portanto, a solicitação foi bem-sucedida. Acontece que o filtro que eles forneceram filtrou todos os resultados. Não cabe ao servidor determinar se é isso que o cliente deseja ou não, pois esse pode ser um resultado esperado para alguns clientes. Se, de alguma forma, for um problema para o código do cliente, essa é a responsabilidade do cliente determinar, verificar e manipular adequadamente. Então isso é claramente 2xx.
Agora, a pergunta é: "Qual 2xx?" Isso depende de como você pretende que o servidor responda.
Os outros não são aplicáveis:
Portanto, deve ser 200 ou 204, e é mais provável que 200 leve a um código de cliente mais simples e robusto (especialmente se você usar uma estrutura de resposta consistente contendo uma lista vazia).
fonte
null
onde normalmente há uma lista), você não colherá os benefícios da consistência mesmo com o 200. No entanto, o que eu descrevo é usar um resposta que seja consistente com a estrutura normal e tenha uma lista vazia para onde a lista de resultados normalmente iria. 204 tira qualquer oportunidade de ter uma resposta tão consistente. Além disso, mesmo nas bibliotecas de clientes HTTP que possuem funções convenientes, geralmente (normalmente?) É necessário fazer uma chamada explícita para analisar o JSON.Não. O uso de 404 para indicar 'sua consulta foi processada, mas não houve correspondências' é péssimo porque:
fluxo condicional com base no tratamento de exceções (ou seja, forçar um resultado não excepcional a criar e manipular uma exceção no cliente que pode não ter desempenho e ser desajeitada)
ambiguidade entre a página 'real' não encontrada, você digitou erros errados no terminal
O que deve ser lembrado é que sempre há um cliente para desserializar a mensagem e o que esse cliente retorna é importante; não a serialização.
Se o cliente retornar nulo, use a serialização de nulo. Se o cliente retornar uma matriz vazia, use []; se o cliente gerar um erro, use 500 e passe a mensagem de erro
fonte
Além da resposta muito boa de @ Ewan:
Se a consulta for do tipo que retorna um conjunto de resultados, o conjunto vazio é logicamente tão apropriado quanto um conjunto de um ou mais. De um modo geral, pelas razões indicadas pelo @Ewan, é mais prejudicial do que benéfico alterar o conjunto vazio para um erro e é simplesmente desnecessário.
Se a consulta for do tipo que procura e retorna um singleton específico (que se espera que seja encontrado, por exemplo, correspondência exata por ID), então não encontrado é uma resposta possível logicamente apropriada.
fonte
Você está assumindo que o código precisa executar uma ação especial quando não há dados retornados, mas esse pode não ser o caso. O código pode estar simplesmente procurando uma contagem de produtos ou anexando os resultados a uma lista ou a várias coisas. Você só deve dar ao usuário um "erro" se houver realmente um erro.
fonte
Quando uso uma API, como cliente, tenho que lidar com casos de "sucesso" diferentes de casos de "erro"; Eu não tenho escolha lá. Portanto, você deve retornar um erro em situações que o cliente deseja tratar de maneira diferente e êxito em situações que o cliente deseja tratar da mesma forma.
Se eu fizer uma consulta que, em teoria, possa retornar qualquer número de resultados, zero, um, duzentos e assim por diante, você deverá retornar "sucesso" sempre que a API fornecer a lista completa de todos os resultados. E, possivelmente, nos casos em que existem muitos resultados, você retornou uma lista parcial de resultados para evitar um tamanho excessivo e existe uma maneira acordada de como eu obteria os outros resultados. Isso porque, como cliente, muitas vezes eu quero lidar com o caso de zero resultado, como o caso de mais resultados. Eu posso tratá-lo de maneira diferente, mas não quero ser forçado.
É diferente no caso em que procuro um valor. Espero exatamente um resultado, o valor que estou procurando. E preciso desse resultado para continuar o que quero fazer de maneira significativa. Aqui é muito mais aceitável retornar um status 404 para o caso em que nenhum valor existe, porque eu preciso lidar com esse caso de maneira diferente.
Resumo: se o cliente espera qualquer número de resultados, de zero a números grandes, retorne "êxito" se todos os resultados forem entregues, mesmo que o número seja zero. Se o cliente espera exatamente um resultado, retorne êxito se o resultado for encontrado e um erro se o resultado não for encontrado.
fonte