Я опишу пример:
я начинаю создавать API для пекарни. API позволит людям искать в своем каталоге продукты для выпечки, например, домашнее мятное печенье с шоколадной крошкой api.examplebakery.com/search?q=.....
.
Кто-то использует это для поиска названного продукта pineapple-banana flavoured cookies
и, очевидно, не найдет никаких результатов.
Должно ли это быть возвращено как ошибка? Поиск не дал сбоя, API выполнил поиск и успешно завершил поиск файлов cookie. API не должен возвращаться 404
, потому что API действительно был найден.
rest
http-response
Берри М.
источник
источник
Ответы:
При наличии результатов выводится список (JSON, на основе вашего комментария). Для запросов без результатов вывод должен быть точно таким же. В списке просто 0 пунктов.
Итак, если ваш ответ обычно такой:
Тогда для запроса с 0 результатами это должно быть так:
Если вы также включите метаданные о количестве «страниц» результатов, ссылок на эти «страницы» и т. Д., То я бы сказал, что существует 1 «страница».
Статус HTTP должен быть таким же, как и при наличии результатов -
200 OK
.204 No Content
Может показаться, что это вариант, но это не потому, что вы на самом деле возвращаете «контент» - пустой список. Если вы считаете, что пустой список не считается «контентом», что, если вы затем измените ответ, предложив варианты написания? Ядром ответа по-прежнему будет пустой список, но теперь «контента» стало еще больше.Для более полезной информации о кодах состояния HTTP, jpmc26 их ответ стоит прочитать.
источник
Всякий раз, когда выбираете код HTTP, вы всегда должны задать этот вопрос:
Всегда решайте, в каком диапазоне должен быть ваш код ответа. Это быстро устраняет множество кодов ответов в качестве опций и (что может быть более важно) упрощает следование семантике кодов. Посмотрите начальные разделы документации кода HTTP для объяснения того, что представляет каждая категория кодов.
В этом случае клиент запросил список результатов, получив фильтр от действующей, существующей конечной точки, и получил разрешение на доступ к нему. Сервер смог обработать запрос и определить соответствующие данные для возврата (без элементов), поэтому запрос был успешным. Просто так получилось, что фильтр, который они дали, отфильтровал все результаты. Сервер не может определить, хотел ли клиент этого или нет, поскольку для некоторых клиентов это может быть ожидаемым результатом. Если это так или иначе является проблемой для клиентского кода, клиент должен определить, проверить и обработать его соответствующим образом. Так что это явно 2xx.
Теперь вопрос: "Какие 2xx?" Это зависит от того, как вы намереваетесь ответить на запрос сервера.
Другие не применимы вообще:
Таким образом, оно должно быть либо 200, либо 204, и 200 с большей вероятностью приведет к более простому и надежному клиентскому коду (особенно если вы используете непротиворечивую структуру ответа, содержащую пустой список).
источник
null
туда, где обычно есть список), вы не сможете воспользоваться преимуществами согласованности даже с 200. Однако, что я описываю, это использование ответ, который согласуется с нормальной структурой и имеет пустой список, куда обычно попадает список результатов. 204 отнимает любую возможность иметь такой последовательный ответ. Кроме того, даже в клиентских библиотеках HTTP, в которых есть вспомогательные функции, вам часто (как правило?) Приходится делать явный вызов для разбора JSON.Нет. Использование 404 для обозначения «ваш запрос был обработан, но совпадений не было» ужасно, потому что:
условный поток, основанный на обработке исключений (т. е. принуждение неисключительного результата к созданию и обработке исключения в клиенте, которое может быть неэффективным и неудобным)
неоднозначность между «реальной» страницей не найдена, вы ввели конечную точку неверные ошибки
Важно помнить, что всегда есть клиент для десериализации сообщения и того, что возвращает этот клиент, это важно; не сериализация.
Если клиент должен вернуть ноль, используйте сериализацию ноль. Если клиент должен вернуть пустой массив, используйте [], если клиент должен сгенерировать ошибку, используйте 500 и передайте сообщение об ошибке
источник
Помимо очень хорошего ответа @ Ewan:
Если запрос является видом, который возвращает набор результатов, то пустой набор логически так же уместен, как набор из одного или набор из нескольких. Вообще говоря, по причинам, которые утверждает @Ewan, преобразование пустого набора в ошибку приносит больше пользы, чем пользы, и это просто не нужно.
Если запрос является видом, который ищет и возвращает конкретный синглтон (который, как ожидается, будет найден, например, точное совпадение по идентификатору), тогда не найден логически подходящий возможный ответ.
источник
Вы предполагаете, что код должен предпринять специальное действие, когда данные не возвращаются, но это может быть не так. Код может просто искать количество продуктов, или добавлять результаты в список или любое количество вещей. Вы должны давать пользователю «ошибку», только если на самом деле есть ошибка.
источник
Когда я использую API, в качестве клиента мне приходится обрабатывать случаи «успеха», отличные от случаев «ошибок»; У меня нет выбора там. Следовательно, вы должны возвращать ошибку в ситуациях, которые клиент хочет обрабатывать по-разному, и успех в ситуациях, которые клиент хочет обрабатывать одинаково.
Если я сделаю запрос, который теоретически мог бы вернуть любое количество результатов, ноль, один, двести и т. Д., Тогда вы должны возвращать «успех» всякий раз, когда API предоставляет полный список всех результатов. И, возможно, в случаях, когда имеется много результатов, вы вернули частичный список результатов, чтобы избежать чрезмерного размера, и существует согласованный способ получения других результатов. Это потому, что, как клиент, я часто хочу обрабатывать случай нулевых результатов, как случай большего количества результатов. Я мог бы относиться к этому по-другому, но я не хочу быть вынужденным.
Это отличается в том случае, если я ищу значение. Я ожидаю ровно одного результата, ценности, которую я ищу. И мне нужен этот один результат, чтобы продолжить то, что я хочу сделать осмысленным образом. Здесь гораздо более приемлемо возвращать статус 404 для случая, когда значение отсутствует, так как в любом случае мне нужно обрабатывать этот случай иначе.
Сводка: если клиент ожидает какого-либо числа результатов, от нуля до большого числа, то возвращает «успех», если все результаты получены, даже если число равно нулю. Если клиент ожидает ровно один результат, верните успех, если результат найден, и ошибку, если результат не найден.
источник