¿Debería "No Resultados" ser un error en una respuesta RESTful?

Describiré un ejemplo:
empiezo a hacer una API para una panadería. La API permitirá a las personas buscar en su catálogo productos para hornear, como el uso de galletas caseras de menta con chispas de chocolate api.examplebakery.com/search?q=......

Alguien usa esto para buscar un producto llamado pineapple-banana flavoured cookiesy obviamente no encontrará ningún resultado.

¿Debería devolverse esto como un error? La búsqueda no falló, la API buscó y concluyó con éxito que no se encontraron cookies. La API no debe regresar 404, porque la API fue encontrada.

Cuando hay resultados, la salida es una lista (JSON, basada en su comentario). Para consultas sin resultados, el resultado debe ser exactamente el mismo. La lista simple tiene 0 elementos.

Entonces, si su respuesta es normalmente esto:

{
    "results": [
        {
            "name": "Pancakes",
            ....
        },
        {
            "name": "French Fries",
            ....
        }
    ]
}

Luego, para una consulta con 0 resultados, debería ser esto:

{
    "results": []
}

Si también incluye metadatos sobre cuántas "páginas" de resultados hay, enlaces a esas "páginas", etc., sugeriría decir que hay 1 "página".

El estado HTTP debe ser el mismo que cuando hay resultados 200 OK.

204 No ContentTambién puede parecer una opción, pero no se debe a que de hecho está devolviendo "contenido": la lista vacía. Si cree que una lista vacía no cuenta como "contenido", ¿qué sucede si luego modifica la respuesta para ofrecer sugerencias de ortografía? El núcleo de la respuesta seguirá siendo una lista vacía, pero ahora hay aún más "contenido".

Para obtener más información útil sobre los códigos de estado HTTP, vale la pena leer su respuesta jpmc26 .

Siempre que elija un código HTTP, siempre debe hacer esta pregunta:

¿Qué puede / hará / debería hacer cualquier cliente arbitrario con la respuesta?

1. ¿El cliente siempre debe tratar la respuesta como un fracaso? Entonces desea 4xx o 5xx, dependiendo de si el problema es la entrada del cliente o los procesos del servidor.
2. ¿Debería el cliente hacer una solicitud en otro lugar? Entonces 3xx es para ti.
3. ¿El servidor hizo lo que el cliente le pidió (tuvo éxito)? Eso es 2xx.

Siempre decida en qué rango debe estar primero su código de respuesta. Hacerlo rápidamente elimina muchos códigos de respuesta como opciones, y (quizás lo más importante) hace que seguir la semántica de los códigos sea mucho más simple. Consulte las secciones iniciales de la documentación del código HTTP para ver las explicaciones de lo que representa cada categoría de códigos.

En este caso, el cliente solicitó una lista de resultados con un filtro de un punto final válido y existente y tiene autorización para acceder a él. El servidor pudo procesar la solicitud y determinar los datos apropiados para devolver (sin elementos), por lo que la solicitud se realizó correctamente. Simplemente sucede que el filtro que dieron filtró todos los resultados. No depende del servidor determinar si esto es lo que el cliente quería o no, ya que puede ser un resultado esperado para algunos clientes. Si de alguna manera es un problema para el código del cliente, es responsabilidad del cliente determinar, verificar y manejar adecuadamente. Entonces esto es claramente 2xx.

Ahora la pregunta es, "¿Qué 2xx?" Esto depende de cómo intente que responda el servidor.

• ¿Enviarás una representación de una lista vacía, como describen otras respuestas ? Si es así, desea 200. 200 significa que el servidor no experimentó problemas y tiene una representación de los resultados para que el cliente los consuma. Esta es probablemente la forma más conveniente de responder para sus consumidores, quienes simplemente pueden analizar la respuesta si hubo resultados o no y luego descubrir cómo manejar ellos mismos una lista vacía.
• 204 no es semánticamente incorrecto aquí, pero tendría que responder sin ningún cuerpo de mensaje . Esto significa que todo el código del cliente tendría que verificar explícitamente los diferentes códigos HTTP (o al menos por la falta de un cuerpo de mensaje) y manejarlos por separado. Es inconveniente y es más probable que conduzca a clientes con mal comportamiento.

Los otros no son aplicables en absoluto:

• 201 está fuera de la cuestión. No creó ningún recurso persistente y no está devolviendo una ubicación a un recurso creado.
• 202 está fuera de la cuestión. La solicitud está hecha; No se está procesando en segundo plano.
• 203 significa que la respuesta se modificó entre el servidor autorizado y el cliente. Su interfaz RESTful es el servidor autorizado, por lo que esto no se aplica aquí.
• 205 no tiene sentido. No necesita que el cliente borre o actualice nada.
• 206 parece estar diseñado para devolver un gran recurso a través de múltiples respuestas. También requiere que el cliente solicite una parte del contenido en los encabezados (por lo que la paginación a través de cadenas de consulta no califica). No aplica aquí.

Por lo tanto, debería ser 200 o 204, y es más probable que 200 conduzca a un código de cliente más simple y robusto (especialmente si usa una estructura de respuesta consistente que contiene una lista vacía).

No. El uso de 404 para indicar 'su consulta fue procesada pero no hubo coincidencias' es horrible porque:

• flujo condicional basado en el manejo de excepciones (es decir, forzar un resultado no excepcional para crear y manejar una excepción en el cliente que puede ser no productiva e incómoda)

• ambigüedad entre la página 'real' no encontrada, escribió los errores incorrectos del punto final

Lo que debe recordar es que siempre hay un cliente para deserializar el mensaje y lo que el cliente devuelve es lo importante; No la serialización.

Si el cliente debe devolver nulo, utilice la serialización de nulo. Si el cliente debe devolver una matriz vacía, use [], si el cliente arroja un error use 500 y pase el mensaje de error

Más allá de la muy buena respuesta de @ Ewan:

Si la consulta es del tipo que devuelve un conjunto de resultados, entonces el conjunto vacío es lógicamente tan apropiado como un conjunto de uno o un conjunto de más. En términos generales, por las razones que @Ewan afirma, hace más daño que bien alterar el conjunto vacío en un error, y es simplemente innecesario.

Si la consulta es del tipo que busca y devuelve un singleton específico (que se espera encontrar, por ejemplo, coincidencia exacta por id), entonces no encontrado es una posible respuesta lógicamente apropiada.

Asume que el código debe tomar una acción especial cuando no se devuelven datos, pero ese podría no ser el caso. El código podría simplemente estar buscando un recuento de productos o agregar los resultados a una lista o cualquier cantidad de cosas. Solo debe dar un "error" a un usuario si realmente hay un error.

Cuando uso una API, como cliente tengo que manejar casos de "éxito" diferentes a los casos de "error"; No tengo otra opción allí. Por lo tanto, debe devolver un error en situaciones que el cliente desea tratar de manera diferente, y el éxito en situaciones que el cliente desea tratar de la misma manera.

Si hago una consulta que, en teoría, podría devolver cualquier número de resultados, cero, uno, doscientos, etc., entonces debería devolver "éxito" siempre que la API entregue la lista completa de todos los resultados. Y, posiblemente, en los casos en que haya muchos resultados, devolvió una lista parcial de resultados para evitar un tamaño excesivo, y hay una forma acordada de cómo obtendría los otros resultados. Eso es porque, como cliente, a menudo quiero manejar el caso de cero resultados como el caso de más resultados. Podría tratarlo de manera diferente, pero no quiero que me obliguen a hacerlo.

Es diferente en el caso de que busque un valor. Espero exactamente un resultado, el valor que estoy buscando. Y necesito ese resultado para continuar lo que quiero hacer de una manera significativa. Aquí es mucho más aceptable devolver un estado 404 para el caso de que no haya ningún valor, porque de todos modos necesito manejar ese caso de manera diferente.

Resumen: si el cliente espera cualquier número de resultados, de cero a números grandes, devuelva "éxito" si se entregan todos los resultados, incluso si el número es cero. Si el cliente espera exactamente un resultado, devuelva el éxito si se encuentra el resultado y un error si no se encuentra el resultado.