Должно ли «Нет результатов» быть ошибкой в ​​ответе RESTful?

Я опишу пример:
я начинаю создавать API для пекарни. API позволит людям искать в своем каталоге продукты для выпечки, например, домашнее мятное печенье с шоколадной крошкой api.examplebakery.com/search?q=......

Кто-то использует это для поиска названного продукта pineapple-banana flavoured cookiesи, очевидно, не найдет никаких результатов.

Должно ли это быть возвращено как ошибка? Поиск не дал сбоя, API выполнил поиск и успешно завершил поиск файлов cookie. API не должен возвращаться 404, потому что API действительно был найден.

При наличии результатов выводится список (JSON, на основе вашего комментария). Для запросов без результатов вывод должен быть точно таким же. В списке просто 0 пунктов.

Итак, если ваш ответ обычно такой:

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

Тогда для запроса с 0 результатами это должно быть так:

{
    "results": []
}

Если вы также включите метаданные о количестве «страниц» результатов, ссылок на эти «страницы» и т. Д., То я бы сказал, что существует 1 «страница».

Статус HTTP должен быть таким же, как и при наличии результатов - 200 OK.

204 No ContentМожет показаться, что это вариант, но это не потому, что вы на самом деле возвращаете «контент» - пустой список. Если вы считаете, что пустой список не считается «контентом», что, если вы затем измените ответ, предложив варианты написания? Ядром ответа по-прежнему будет пустой список, но теперь «контента» стало еще больше.

Для более полезной информации о кодах состояния HTTP, jpmc26 их ответ стоит прочитать.

Всякий раз, когда выбираете код HTTP, вы всегда должны задать этот вопрос:

Что может / будет / должен любой произвольный клиент сделать с ответом?

1. Должен ли клиент всегда рассматривать ответ как неудачу? Затем вы хотите 4xx или 5xx, в зависимости от того, является ли проблема входом клиента или процессов сервера.
2. Должен ли клиент сделать запрос в другом месте? Тогда 3xx для вас.
3. Сделал ли сервер то, что просил клиент (успешно)? Это 2хх.

Всегда решайте, в каком диапазоне должен быть ваш код ответа. Это быстро устраняет множество кодов ответов в качестве опций и (что может быть более важно) упрощает следование семантике кодов. Посмотрите начальные разделы документации кода HTTP для объяснения того, что представляет каждая категория кодов.

В этом случае клиент запросил список результатов, получив фильтр от действующей, существующей конечной точки, и получил разрешение на доступ к нему. Сервер смог обработать запрос и определить соответствующие данные для возврата (без элементов), поэтому запрос был успешным. Просто так получилось, что фильтр, который они дали, отфильтровал все результаты. Сервер не может определить, хотел ли клиент этого или нет, поскольку для некоторых клиентов это может быть ожидаемым результатом. Если это так или иначе является проблемой для клиентского кода, клиент должен определить, проверить и обработать его соответствующим образом. Так что это явно 2xx.

Теперь вопрос: "Какие 2xx?" Это зависит от того, как вы намереваетесь ответить на запрос сервера.

• Вы отправите обратно представление пустого списка, как описывают некоторые другие ответы ? Если это так, вы хотите 200. 200 означает, что на сервере не возникло проблем, и он имеет представление результатов для использования клиентом. Вероятно, это наиболее удобный способ ответа для ваших потребителей, которые могут просто проанализировать ответ независимо от того, были ли результаты или нет, а затем выяснить, как обрабатывать пустой список самостоятельно.
• 204 не является семантически неправильным здесь, но вы должны будете ответить без какого-либо тела сообщения . Это означает, что весь код клиента должен был бы явно проверять различные HTTP-коды (или, по крайней мере, на отсутствие тела сообщения) и обрабатывать их отдельно. Это неудобно и, скорее всего, приведет к плохому поведению клиентов.

Другие не применимы вообще:

• 201 не может быть и речи. Вы не создали постоянных ресурсов и не возвращаете местоположение в созданный ресурс.
• 202 не может быть и речи. Запрос выполнен; это не обработка в фоновом режиме.
• 203 означает, что ответ был изменен между уполномоченным сервером и клиентом. Ваш интерфейс RESTful является официальным сервером, поэтому здесь это не применимо.
• 205 не имеет смысла. Вам не нужен клиент, чтобы очистить или обновить что-либо.
• 206, похоже, предназначен для возврата большого ресурса по нескольким ответам. Также требуется, чтобы клиент запрашивал часть содержимого в заголовках (поэтому разбиение на страницы через строки запроса не подходит). Не применимо здесь.

Таким образом, оно должно быть либо 200, либо 204, и 200 с большей вероятностью приведет к более простому и надежному клиентскому коду (особенно если вы используете непротиворечивую структуру ответа, содержащую пустой список).

Нет. Использование 404 для обозначения «ваш запрос был обработан, но совпадений не было» ужасно, потому что:

• условный поток, основанный на обработке исключений (т. е. принуждение неисключительного результата к созданию и обработке исключения в клиенте, которое может быть неэффективным и неудобным)

• неоднозначность между «реальной» страницей не найдена, вы ввели конечную точку неверные ошибки

Важно помнить, что всегда есть клиент для десериализации сообщения и того, что возвращает этот клиент, это важно; не сериализация.

Если клиент должен вернуть ноль, используйте сериализацию ноль. Если клиент должен вернуть пустой массив, используйте [], если клиент должен сгенерировать ошибку, используйте 500 и передайте сообщение об ошибке

Помимо очень хорошего ответа @ Ewan:

Если запрос является видом, который возвращает набор результатов, то пустой набор логически так же уместен, как набор из одного или набор из нескольких. Вообще говоря, по причинам, которые утверждает @Ewan, преобразование пустого набора в ошибку приносит больше пользы, чем пользы, и это просто не нужно.

Если запрос является видом, который ищет и возвращает конкретный синглтон (который, как ожидается, будет найден, например, точное совпадение по идентификатору), тогда не найден логически подходящий возможный ответ.

Вы предполагаете, что код должен предпринять специальное действие, когда данные не возвращаются, но это может быть не так. Код может просто искать количество продуктов, или добавлять результаты в список или любое количество вещей. Вы должны давать пользователю «ошибку», только если на самом деле есть ошибка.

Когда я использую API, в качестве клиента мне приходится обрабатывать случаи «успеха», отличные от случаев «ошибок»; У меня нет выбора там. Следовательно, вы должны возвращать ошибку в ситуациях, которые клиент хочет обрабатывать по-разному, и успех в ситуациях, которые клиент хочет обрабатывать одинаково.

Если я сделаю запрос, который теоретически мог бы вернуть любое количество результатов, ноль, один, двести и т. Д., Тогда вы должны возвращать «успех» всякий раз, когда API предоставляет полный список всех результатов. И, возможно, в случаях, когда имеется много результатов, вы вернули частичный список результатов, чтобы избежать чрезмерного размера, и существует согласованный способ получения других результатов. Это потому, что, как клиент, я часто хочу обрабатывать случай нулевых результатов, как случай большего количества результатов. Я мог бы относиться к этому по-другому, но я не хочу быть вынужденным.

Это отличается в том случае, если я ищу значение. Я ожидаю ровно одного результата, ценности, которую я ищу. И мне нужен этот один результат, чтобы продолжить то, что я хочу сделать осмысленным образом. Здесь гораздо более приемлемо возвращать статус 404 для случая, когда значение отсутствует, так как в любом случае мне нужно обрабатывать этот случай иначе.

Сводка: если клиент ожидает какого-либо числа результатов, от нуля до большого числа, то возвращает «успех», если все результаты получены, даже если число равно нулю. Если клиент ожидает ровно один результат, верните успех, если результат найден, и ошибку, если результат не найден.