REST API - Что нужно вернуть, когда критерии поиска (queryParams) не дают никаких результатов.

Question

Я разрабатываю API REST и по всему API, который мы использовали HTTP Не найден/404, когда объект/ресурс, который мы пытаемся получить, не существует.

Ex: http://host/someobject/1 

Но текущий сценарий немного отличается. У меня есть URI, который ищет данные с параметрами запроса.

Ex: http://host/someObject/find?param1=param1value&param2=param2value 

Параметры запроса являются необязательными, но для успешного запроса должен быть предоставлен хотя бы один критерий. В настоящее время я возвращаю пустой список, когда результат поиска пуст, если URI существует, но данные на данный момент отсутствуют.

Может ли кто-нибудь пролить свет на этот сценарий? Должен ли я возвращать пустой массив с кодом состояния 200 или что-то еще?

Answer 1

TL; DR - возвращает то же самое, вы бы вернуться с N результатов, используя N = 0.

http://host/someObject/find?param1=param1value&param2=param2value 

Хранить в помните, что с точки зрения REST/HTTP URI выше: не запрос; это идентификатор информационного ресурса. Часть идентификатора (который называется Query by RFC-3986) - это просто «неиерархические данные».

Тот факт, что ваша реализация анализирует URI и использует токены, которые он находит в качестве входных данных для запроса, является детальностью реализации и намеренно скрывается от клиента по равномерному интерфейсу. (Рассмотрим, например, случай, когда клиентский запрос GET проходит через кеш между клиентом и сервером, кеш может использовать URI в качестве поиска в хранилище значений ключей, и - поиск там представления - отправит результат возвращается клиенту без пересылки запроса на сервер).

В идеале ваши ресурсы и их представления будут стабильными, даже если ваша реализация не может быть.

Параметры запроса являются необязательными, но для успешного запроса должен быть предоставлен хотя бы один критерий. В настоящее время я возвращаю пустой список, когда результат поиска пуст, если URI существует, но данные на данный момент отсутствуют.

Perfect.

Я предполагаю, что комментарий от вас говорит, что моя реализация в порядке?

Да.

Также я обнаружил, что некоторые люди, говорящие глагол, не должны быть там, а представление должно быть объектами /? Param = value или Object? Param = value.

Краткий обзор

REST не волнует, что написание используется для идентификатора ресурса Ни делает веб - насколько другие части Интернета обеспокоены тем, ваши идентификаторы URI непрозрачны. Клиентский код не должен интерпретировать идентификаторы или полагаться на их интерпретацию каким-либо образом. Единственное, что должно ухаживать, это исходный сервер (которому необходимо перенаправить идентификатор на соответствующую реализацию).

«Правило», которое вы цитируете, аналогично руководству по стилю кодирования, рекомендующему лучшие практики для имен переменных. Модификация для правила основана на REST и сети; не по спецификации, а по более глубоким идеям .... Fielding's definition of resources:

Ключевая абстракция информации в REST - это ресурс. Любая информация, которую можно назвать, может быть ресурсом: документ или изображение, временная служба (например, «сегодняшняя погода в Лос-Анджелесе»), коллекция других ресурсов, не виртуальный объект (например, человек) и т. Д. , Другими словами, любое понятие, которое может быть целью гипертекстовой ссылки автора, должно соответствовать определению ресурса.

Компоненты REST выполняют действия над ресурсом, используя представление для захвата текущего или предполагаемого состояния этого ресурса и передачи этого представления между компонентами.

Отсюда следует, что любой ресурс, который возвращает представление должна быть вещью что имеет состояние. Таким образом, рекомендации по наименованию поощряют написания, которые идентифицируют ресурс как существительное, а не глагол.

«Найти объекты, которые удовлетворяют этим ограничениям» - это то, что говорит ваш URI, но это не соответствует концепции ресурсов. Руководящие принципы побуждают вас вместо этого думать: «Получите мне текущее состояние коллекции объектов, удовлетворяющих следующему ограничению», а затем выберите идентификатор, соответствующий этому ресурсу.

Я довольно смущен, когда я читаю эти различные блоги с различными мнениями

• Это не ваша вина
• Вы бы до сих пор путают, если вы являетесь носителем английского языка

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

В случае REST искажение дошло до того момента, когда люди, которые знали оригинальную историю, начали искать новое имя, чтобы иметь возможность повторно вводить оригинальные идеи.

Answer 2

As 404 означает: 404 - Не найдено - Ресурс позади URI отсутствует. Я бы сказал, что возврат пустого списка действителен, когда URI и аргументы действительны.

Вы не могли бы возвращать 204 с ним: 204 No Content

Answer 3

На мой взгляд, как 200 с пустым списком, так и 204 Нет содержимого найдено правильная реализация.

200 успешных означает, что вы смогли успешно выполнить операцию, и вы возвращаете результат. Пустой список - это действительный набор результатов.

204 означает, что операция была успешно выполнена, и сервер ничего не возвращал. Так что это также справедливо.

мир RESTful настолько утончен, что в конце его когда-нибудь он подходит к вашим личным предпочтениям, и мои личные предпочтения будут 200 с пустым списком.