Чи має бути "Без результатів" помилка у відповіді на 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. Чи зробив сервер те, що клієнт запитав (вдалося)? Це 2xx.

Завжди вирішуйте, в якому діапазоні має бути ваш код відповіді. Це швидко виключає безліч кодів відповідей як варіантів, і (можливо, що важливіше), це супроводжує семантику кодів набагато простіше. Пояснення, що представляє кожна категорія кодів, див. У початкових розділах документації щодо коду HTTP .

У цьому випадку клієнт запитав список результатів, який отримав фільтр з дійсної, існуючої кінцевої точки та має дозвіл на доступ до нього. Сервер зміг обробити запит і визначити відповідні дані для повернення (немає елементів), тому запит був успішним. Просто буває, що фільтр, який вони дали, відфільтрував усі результати. Сервер не залежить від того, хотів чи ні клієнт, оскільки це може бути очікуваним результатом для деяких клієнтів. Якщо це якимось чином проблема з клієнтським кодом, це обов'язок клієнта визначати, перевіряти та обробляти належним чином. Тож це однозначно 2х.

Тепер питання: "Який 2xx?" Це залежить від того, як ви плануєте відповідати серверу.

• Ви надішлете подання порожнього списку, як описано в деяких інших відповідях ? Якщо це так, ви хочете, щоб 200. 200 означає, що сервер не мав проблем і має представлення результатів для клієнта. Це, мабуть, найзручніший спосіб відповісти для своїх споживачів, які можуть просто проаналізувати відповідь, були результати чи ні, а потім зрозуміти, як самостійно обробити порожній список.
• 204 тут не семантично помиляється, але вам доведеться відповідати без будь-якого повідомлення . Це означає, що весь клієнтський код повинен явно перевірити наявність різних HTTP-кодів (або принаймні на відсутність тіла повідомлення) та обробляти їх окремо. Це незручно і, швидше за все, призведе до погано поводиться клієнтів.

Інші взагалі не застосовуються:

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

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

Ні, використання 404 для позначення "ваш запит оброблено, але не було відповідностей" є жахливим, оскільки:

• умовний потік, що базується на обробці винятків (тобто змушувати невиключний результат створювати та обробляти виняток у клієнта, який може бути неприйнятним та незручним)

• неоднозначність між "реальною" сторінкою не знайдено, ви ввели кінцеву точку помилок

Що слід пам’ятати, це те, що клієнт завжди десериалізує повідомлення та його те, що той клієнт повертає, що важливо; не серіалізація.

Якщо клієнт повинен повернути null, використовуйте серіалізацію null. Якщо клієнт повинен повернути порожній масив, використовуйте [], якщо клієнт повинен кинути помилку на використання 500 і передати повідомлення про помилку

Дуже гарна відповідь Евана:

Якщо запит виглядає таким чином, який повертає набір результатів, то порожній набір логічно настільки ж відповідний, як набір одного або набір більше. Взагалі кажучи, з причин, які заявляє @Ewan, це робить більше шкоди, ніж користі, щоб змінити порожній набір в помилку, і це просто непотрібно.

Якщо запит виглядає таким чином, який шукає і повертає певний сингтон (який, як очікується, буде знайдений, наприклад, точне відповідність за id), то не знайдений - це логічно відповідний можливий відповідь.

Ви припускаєте, що код повинен вжити спеціальних дій, коли даних не повернуто, але це може бути не так. Код може просто шукати кількість товарів або додавати результати до списку чи будь-якої кількості речей. Ви повинні давати користувачеві "помилку", лише якщо насправді є помилка.

Коли я використовую API, як клієнт мені доводиться обробляти "успішні" випадки, відмінні від випадків "помилки"; У мене немає вибору там. Тому вам слід повернути помилку в ситуаціях, до яких клієнт хоче ставитися по-різному, і успіху в ситуаціях, коли клієнт хоче ставитися до того ж.

Якщо я роблю запит, який теоретично міг би повернути будь-яку кількість результатів, нуль, одну, двісті і так далі, то ви повинні повертати «успіх», коли API надає повний список усіх результатів. І, можливо, у випадках, коли результатів багато, ви повернули частковий список результатів, щоб уникнути зайвого розміру, і є узгоджений спосіб, як я отримав би інші результати. Це тому, що, як клієнт, мені часто хочеться обробляти випадок нульових результатів, як, наприклад, більше результатів. Я можу ставитися до цього по-різному, але я не хочу, щоб мене примушували.

У тому випадку, якщо я шукаю значення. Я очікую рівно одного результату - значення, яке я шукаю. І мені потрібен один результат, щоб продовжувати те, що я хочу зробити, змістовно. Тут набагато прийнятніше повернути статус 404 для випадку, коли немає значення, оскільки мені так чи інакше потрібно обробляти цей випадок.

Підсумок: Якщо клієнт очікує будь-якої кількості результатів - від нуля до великої кількості, то поверніть "успіх", якщо всі результати будуть доставлені, навіть якщо число дорівнює нулю. Якщо клієнт очікує рівно одного результату, тоді поверніть успіх, якщо результат буде знайдено, і помилка, якщо результат не буде знайдено.