RESTful API - це відсутність речі

Уявіть собі API, щоб визначити, чи вибрала людина свою духовну тварину. У них можуть бути лише нульові або одні спиртні тварини.

В даний час:

/person/{id}/selectedSpiritAnimal

коли вони вибрали, тварина повертає http 200 і {selectedAnimal:mole}

але коли вони не мають вибору, він повертає http 404.

Це робить мою спиртну тварину нещасною, оскільки ми представляємо дійсну проблему домену - ще не вибравши спиртну тварину - як помилку HTTP.

Крім того, як бізнес - Erm Sprit-Animal-Hampers-R-us - ми хочемо знати, коли у когось немає вибору, щоб ми могли їх підказати.

Яка краща відповідь тут:

HTTP 200 і {selectedAnimal:null}

або навіть більш чітко

HTTP 200 і {selectedAnimal:null, spiritAnimalSelected: false}

Або краще повернути 404? Оскільки так, як this image has not yet been uploadedпри перегляді зображення в Інтернеті було б 404, this person has not selected a spirit animalможе бути 404

Це запитання було запропоновано як дублікат, але це питання стосується інакше дійсної URL-адреси, яка запитується, коли програма налаштована таким чином, щоб не дозволяти змінити цю URL-адресу.

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

Тож це не «ділова логіка», а скоріше обставина, коли відсутність речі має значення (можливо, так багато моїх колег стверджують, що 404 все-таки є правильним), але я не знаю, як це позначити на спец.

Дуже важко вибрати відповідь. Я передумав кілька разів під час розмови тут і тієї, що триває на роботі.

Що тут вирішується для мене, це те, що специфікація говорить про те, що 4xx - це коли клієнт допустив помилку . У цьому випадку клієнту сказали очікувати відповіді від вибраного URL-адресиSpiritAnimal, тому він не помилився.

Консенсус серед моїх колег полягає в тому, що це симптом поганого дизайну API

Напевно, було б краще, щоб ми просто просили / person / {id}, і це повертає набір зв’язків для особи ... тоді, якщо вам не надано / selectedSpiritAnimal (якщо людина не має вибору), але ви називати це все одно, то 404 має сенс. Або що ви реалізуєте часткові відповіді і нехай / person / {id} повертає більш повний документ, якщо клієнт не вимагає підмножини даних

Коди HTTP 4xx, мабуть, не є правильним вибором для цього сценарію. Ви заявляєте, що мати тварин з нульовим спиртом є дійсним станом, і маршрут API person/{id}/selectedSpiritAnimalбуде враховувати, чи є у людини такий idчи ні.

Відповіді HTTP 4xx зарезервовані для ситуації, коли клієнт зробив щось неправильне в запиті (див . Архів w3 оригінальної специфікації ). Але клієнт робить обґрунтований запит, незалежно від того, чи є у людини idдух тварини.

Тому я схиляюся до другого рішення, використовуючи правильно відформатований корпус JSON у відповіді та код HTTP 2xx.

Тепер, якщо ви отримуєте такий запит, і виявляється, що людини idне існує, 4xx-код має більше сенсу.

Дозвольте познайомити вас із моделлю зрілості Річардсона .

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

Ваша людина повинна жити під URI, /person/{id}а тварина має жити /spiritanimal/{id}. Людина повинна вказати, що має дух тварини, використовуючи посилання на тварину.

Давайте уявимо собі людину на ім'я Боб, у якої ідентифікатор 123 та тварина-дух-єдиноріг.

GET /person/123

повернувся б;

{
  "name": "Bob",
  "links": [
    {
      "rel": "spiritanimal",
      "uri": "/spiritanimals/789"
    }
  ]
}

Тепер кожен, хто читає людину 123, буде знати, що у них є духовна тварина та має URI, де вони можуть отримати більше інформації про неї.

GET /spitiranimal/789

може повернутися

{
  "type": "Unicorn"
}

Тепер давайте уявимо собі людину на ім’я Фред, у якої ідентифікатор 456 і жодна духовна тварина.

GET /person/456

повернувся б;

{
  "name": "Fred",
  "links": [
  ]
}

Тепер кожен, хто читає людину 456, буде знати, що у них немає духової тварини, як немає зв'язку. Немає необхідності використовувати будь-який код статусу HTTP, щоб представити відсутність зв'язку.

Це відповідна URL-адреса для отримання спиртних тварин; тому помилка 404 недоцільна. 404 - це представлення технічної проблеми, а не логічної проблеми.

Відповідне рішення - повернути http 200 і {"selectedAnimal": null}

У вас повинен бути окремий веб-метод, /person/{id}/hasSelectedSpiritAnimalякий повертається {"isSpiritAnimalSelected": false}. Позаду, він може або не може робити один і той же метод виклику, просто повертаючи помилковий, якщо недійсний, але це вирішується, а не споживчий код.

Краще уникати поєднання роздільних запитів в одному веб-методі без вагомих причин для цього, навіть якщо запити тісно пов'язані.

Ваша кінцева точка являє собою не просто тварину; це тварина чи її нестача. Це значення найкраще представлені Optional/ Maybe/ Nullable/ і т.д.

Отже, законними значеннями (як у 200 ОК) можуть бути:

• {'animal': <some animal>, 'selected': true}
• {'animal': null, 'selected': false}

Я міг собі уявити , що DELETEметод, при застосуванні до кінцевої точки, можна встановити , 'selected'щоб falseзнову, тобто скинути вибрану тварину.

Тут, звичайно, можна кинути 'selected'ключ, він відображається лише для наочності; рядок vs nullдосить для розрізнення.

Ви повинні використовувати 404.

Код стану 404 (не знайдено) вказує на те, що сервер-джерело не знайшов поточне представлення для цільового ресурсу

RFC7231

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 404 Not Found
Content-Type: text/plain
Date: Mon, 25 Sep 2017 00:00:00 GMT

this person has not selected a spirit animal

Оскільки ви створюєте інтерфейс програмування, а не людський інтерфейс, текст 404 необов’язковий.

Я вважаю за краще це, бо я максимально віддаю перевагу стандартним протоколам. У HTTP є спосіб представити неіснуюче, і саме це я б використав.

EDIT: Припустимо, ви додали функцію, де користувачі могли вибрати, чи слід ділитися своїми духовими тваринами, а хтось не поділився нею. Ви повернете 200 ОК null, або 200 ОК "Unauthorized? Або ви використовуєте стандарт 401 Несанкціонований / 403 Заборонений? Це здається безпосередньо аналогічним тому, що вибирати не в першу чергу.

Якщо ви хочете використати 200 OK + JSON, вам слід повернутися null.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

null

Утримуйте речі в чистоті. Створіть більше обгортання лише за потреби.