Um erro 5xx é normalmente usado para indicar que o servidor encontrou um erro e não pode concluir a solicitação. Se o servidor receber a solicitação, poderá analisá-lo com êxito e, em seguida, realizará o trabalho, que não deverá retornar um erro 5xx.
Não tenho certeza se existe algum tipo de convenção sobre o que retornar se uma consulta não gerar resultados. Eu vi tanto o que você descreve (um 200 com um corpo que contém uma mensagem) quanto um 404 indicando que os resultados não foram encontrados. Os 200 provavelmente fazem mais sentido - a solicitação foi concluída com sucesso e não houve problemas com a solicitação do cliente ou durante o processamento do pedido pelo servidor. Um corpo pode entregar uma mensagem ao cliente.
Eu trataria os dois exemplos ( http://example.com/restapi/deviceinfo?id=123
e http://example.com/restapi/device/123/info
) da mesma forma - o 123
é um parâmetro. Ambos os casos são formas diferentes de estruturar uma solicitação para obter informações do dispositivo para um dispositivo com o ID 123.
Primeiro, eu consideraria autorização e autenticação. Se o usuário não tiver as permissões apropriadas, retornaria um 403 ou um 401, conforme apropriado. Embora seja chamado de "Não autorizado", meu entendimento é que 401 é mais sobre autenticação e 403 é sobre não autorizado ou permissão negada. Eu não seria muito exigente aqui, no entanto, se você quisesse manter o 403 para todos os erros de autenticação e autorização.
Então, eu lidaria com o ID. Com base no seu exemplo, parece que é um ID numérico. Se um valor não numérico fosse fornecido, retornaria um 400. Se o parâmetro pudesse ser um identificador de dispositivo válido, eu continuaria com o processamento. Se houvesse outros argumentos, eles também seriam verificados aqui. Eu esperaria que o corpo da resposta contivesse informações apropriadas sobre o motivo pelo qual a solicitação foi ruim.
Se todos os parâmetros fossem válidos, começaria a processar a solicitação. Se o sistema ou qualquer dependência (um banco de dados, um serviço de terceiros, outro serviço interno) não estiver disponível, retornaria um código 5xx - 503 seria específico, mas um 500 também seria aceitável. Em ambos os casos, eu retornaria um corpo com detalhes adicionais. Considere que, se uma dependência externa relatar um 408 Request Timeout, eu comia isso e retornava um 500 para meu cliente, permitindo que um cliente recebesse um 408 somente se a solicitação ao meu sistema atingisse o tempo limite. Se o sistema for capaz de completar o pedido, eu retornaria um 200 e o corpo apropriado.
204 pode ser útil em alguns casos, mas impede que você envie um corpo de resposta. Especialmente em uma configuração de API, enviar um corpo de resposta com informações que podem ser inseridas em um mecanismo de criação de relatórios ou relatórios parece ser a decisão correta na maioria dos casos.
O único momento em que um 404 seria retornado seria se o servidor não tivesse um ponto de extremidade /deviceinfo
ou% endpoint /device/:id/info
.
Eu não consideraria um ID que não fosse o mesmo que o recurso não encontrado. O recurso é a informação do dispositivo para um dispositivo específico (no seu exemplo). Retornar um 404 significaria que o recurso (as informações do dispositivo) não existe. Um 200 com um corpo apropriado significa que o sistema pode, de fato, fornecer informações sobre o dispositivo. Pode ou não haver um dispositivo com o ID especificado.