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

Ми пишемо API для системи, є запит, який повинен повернути дерево організації або дерево цілей.

Дерево організації - це організація, в якій присутній користувач. Іншими словами, це дерево завжди має існувати. В організації завжди повинно бути дерево цілі. (саме тут і почався аргумент). У випадку, коли дерева не існує, мій колега вирішив, що було б правильно відповісти на відповідь з кодом статусу 200. А потім почав просити мене виправити код, оскільки програма розпадалася, коли дерева немає.

Я спробую пощадити полум'я і лють.

Я запропонував підняти помилку 404, коли немає дерева. Хоча б мені дали знати, що щось не так. Під час використання 200 я повинен додати спеціальну перевірку до своєї відповіді на зворотній виклик успіху для обробки помилок. Я сподіваюся отримати об’єкт, але, можливо, я отримаю порожню відповідь, тому що нічого не знайдено. Цілком справедливо звучить відповідь як 404. І тоді почалася війна, і я отримав повідомлення про те, що я не розумію схему коду статусу HTTP. Тож я тут і запитую, що з цим 404 не так? У мене навіть з’явився аргумент « Нічого не знайшли , тому правильно повернути 200». Я вважаю, що це неправильно, оскільки дерево повинно бути завжди присутнє. Якщо ми нічого не знайшли і чогось очікуємо, це має бути 404.

Більше інформації,

Я забув додати отримані URL-адреси.

Організації

/OrgTree/Get

Цілі

/GoalTree/GetByDate?versionDate=...
/GoalTree/GetById?versionId=...

Моя помилка, обидва параметра потрібні. Якщо надана будь-яка версіяDate, яку можна проаналізувати на дату, вона поверне закриту редакцію. Якщо ви введете щось у минулому, воно поверне першу редакцію. Якщо за Id з ідентифікатором, який не існує, я підозрюю, що він поверне порожню відповідь із 200.

Додатково

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

також я пов’язав це (один подібний, але я не можу його знайти)

http://viswaug.files.wordpress.com/2008/11/http-headers-status1.png

Якщо є сумніви, зверніться до документації . Переглядаючи визначення W3C щодо кодів статусу HTTP, нам це дає:

200 ОК - Запит вдався. Інформація, що повертається з відповіддю, залежить від методу, який використовується у запиті.

404 Not Found - Сервер не знайшов нічого, що відповідатиме URI-запиту.

У контексті Вашого API це дуже залежить від того, як створюються запити та як отримуються об'єкти. Але моє тлумачення завжди було таке:

• Якщо я запитую конкретний об'єкт, і він існує 200код повернення , якщо його немає, поверніть правильний 404код.
• Але, якщо я запитую набір об’єктів, які відповідають запиту, нульовий набір - це дійсна відповідь, і я хочу, щоб він повернувся з 200кодом. Обґрунтуванням цього є те, що запит був дійсним, він вдався і запит нічого не повернув.

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

Я думаю, що Вікіпедія найкраще:

200 ОК - ... Фактична відповідь залежатиме від використовуваного методу запиту. У запиті GET відповідь міститиме сутність, що відповідає запитуваному ресурсу.

404 Not Found - запитуваний ресурс не вдалося знайти, але він може бути знову доступний у майбутньому. Подальші запити клієнта допустимі.

Мені це здається досить зрозумілим.

Стосовно прикладу запитів

/GoalTree/GetByDate?versionDate=...
/GoalTree/GetById?versionId=...

Що стосується формату, ви сказали, ви завжди повертаєте найближчу редакцію до цієї дати. Він ніколи не поверне об’єкт, тому він завжди повинен повертатися 200 OK. Навіть якщо це вдалося прийняти діапазон дат, і логіка полягала в тому, щоб повернути всі об'єкти в межах цього терміну, повертаючи 200 ОК - 0 результатів, це нормально, тому саме для цього був запит - набір речей, які відповідають цим критеріям.

Однак останнє відрізняється тим, що ви просите конкретний об'єкт , імовірно унікальний, з цією ідентичністю. Повернення 200 OKв цьому випадку неправильне, оскільки запитуваний ресурс не існує та не знайдений .

Щодо вибору кодів статусу

• 2xx коди Скажіть UA, що він зробив правильно , запит спрацював. Це може продовжувати робити це в майбутньому.
• 3xx коди Скажіть UA, що ви запитували, ймовірно, раніше працювали, але ця річ зараз в іншому місці. Надалі UA може розглянути можливість просто перейти до переадресації .
• 4xx коди Скажіть UA, що він зробив щось не так , запит, який він сконструював, не є належним і не повинен намагатися повторити його, хоча б дещо змінивши.
• 5xx коди Скажіть UA, що сервер якось зламаний . Але ей, що запит може спрацювати в майбутньому, тому немає причин не спробувати його ще раз. (за винятком 501, що більше 400 випусків).

Ви згадували в коментарі, використовуючи код 5xx, але ваша система працює. Був заданий запит, який не працює, і його потрібно повідомити в UA. Як би ви їх не нарізали, це територія 4xx.

Розглянемо, як іноземець запитує нашу Сонячну систему

Чужий: Комп'ютер, скажіть, будь ласка, всі планети, які мешкають люди.

Комп'ютер: знайдено 1 результат. Земля

Чужий: Комп'ютер, скажіть, будь ласка, про Землю .

Комп'ютер: Земля - ​​здебільшого нешкідливий.

Чужий: Комп'ютер, розкажіть, будь ласка, про всі планети, які мешкають люди, поза поясом астероїдів.

Комп'ютер: знайдено 0 результатів.

Чужий: Комп'ютер, будь ласка, знищити Землю.

Комп'ютер: 200 ОК.

Чужий: Комп'ютер, скажіть, будь ласка, про Землю .

Комп'ютер: 404 - Не знайдено

Чужий: Комп'ютер, скажіть, будь ласка, всі планети, які мешкають люди.

Комп'ютер: знайдено 0 результатів.

Чужий: Перемога для могутньої Іркенської імперії!

Ігноруючи той факт, що / GoalTree / Get * виглядає як дієслово, а не ресурси, ви завжди повинні повертати 200, оскільки URI / GoalTree / Get * представляють ресурси, які завжди доступні для доступу, і це не помилка клієнта, якщо в результаті немає дерева запит. Просто поверніть 200 з порожнім набором, коли немає сутності, яку потрібно повернути.

Ви використовуєте 404, якщо ресурс не знайдено, а не тоді, коли немає сутності.

Поставте це іншим способом, якщо ви хочете повернути 404 для своїх об'єктів, то дайте їм власні URI.

Це цікаве запитання, адже все стосується специфікації системи.

Відповідь ime96 переконала, що 404 не буде належною відповіддю, оскільки сімейство кодів 4xx в основному стосується помилок користувача / клієнта , а це не одна. URL-адреса добре сформована, і дерево повинно бути там; якщо це не так, система знаходиться в непослідовному стані!

Тому це помилка сервера , тобто щось із сімейства 5xx. Можливо, загальна помилка в 500 внутрішніх серверів або служба 503 недоступна (служба "приносить мені дерево, яке повинно бути там").

Я б сказав, що код відповіді 200 або 404 може бути дійсним , залежно від того, як ви дивитесь на ситуацію.

Вся справа в тому, що коди відповідей HTTP визначаються в контексті сервера , який може доставляти різні ресурси на основі їх URL-адреси. У цьому контексті значення 200 OKі 404 Not Foundабсолютно однозначні: перший говорить "ось ресурс, про який ви попросили", а другий каже "вибачте, у мене немає такого ресурсу".

Однак у вашій ситуації у вас є додатковий рівень додатка між HTTP-сервером та фактичними ресурсами (деревами), які запитуються. Додаток займає свого роду проміжний простір, який недостатньо добре вирішений у специфікації HTTP.

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

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

З іншого боку, якщо ваша точка зору полягає в тому, що програма - це запитуваний ресурс , тоді, очевидно, веб-сервер повинен повернути відповідь 200 ; зрештою, додаток було знайдено та виконано правильно. Очевидно, що в цьому випадку програма фактично повинна повернути дійсний орган відповіді у очікуваному форматі, вказуючи (використовуючи той протокол вищого рівня, який формат кодує), що фактичних даних, що відповідають запиту, не знайдено.

Обидва ці точки зору можуть мати сенс. У більшості випадків , принаймні для додатків, призначених для прямого доступу через HTTP за допомогою звичайного веб-браузера, я віддаю перевагу колишньому виду : користувачеві взагалі не цікаво внутрішніх деталей, таких як різниця між сервером і додатком, вони просто дбає про те, чи є потрібні їм дані чи ні.

Однак у конкретному випадку програми, призначеної для спілкування з іншими комп'ютерними програмами за допомогою користувацького протоколу API високого рівня, використовуючи HTTP лише як транспортний рівень низького рівня , є аргумент на користь останньої точки зору : клієнти, що взаємодіють з таким додатком, на рівні HTTP - все, що їм дійсно важливо , - це те, чи вдалося їм успішно зв’язатися із програмою чи ні. Все інше в таких випадках часто більш природно передається за допомогою протоколу вищого рівня.

У будь-якому випадку, незалежно від того, якому з перерахованих вище поглядів ви надаєте перевагу, є кілька деталей, про які слід пам’ятати. Одне полягає в тому, що в багатьох випадках може бути змістовне розмежування (по суті) порожнього ресурсу від неіснуючого .

На рівні HTTP порожній ресурс буде просто позначений кодом відповіді 200 та порожнім органом відповіді, тоді як неіснуючий ресурс буде позначений відповіддю 404 та органом ресурсу, що пояснює відсутність ресурсу. У протоколі API більш високого рівня, як правило, вказується на неіснуючий ресурс у відповіді на помилку, що містить відповідний специфічний для протоколу код / ​​повідомлення про помилку, тоді як порожня відповідь буде просто нормальною структурою відповіді без елементів даних.

(Зверніть увагу, що ресурс не повинен бути буквально нульовим байтом, щоб він був "порожнім" у сенсі, про який я маю на увазі вище. Наприклад, результат пошуку без відповідних елементів вважатиметься порожнім у широкому сенсі, як і результат запиту SQL з немає рядків або XML-документа, що не містить фактичних даних.)

Крім того , звичайно, якщо додаток дійсно вважає , що запитувана subresource повинна бути там, але не може його знайти, то третій можливий код відповіді існує: 500 Internal Server Error. Така відповідь має сенс, якщо існування ресурсу є передбачуваною умовою програми, так що його відсутність обов'язково вказує на внутрішню несправність.

Нарешті, завжди слід пам’ятати про закон Постела :

" Будьте консервативними в тому, що ви надсилаєте, і будьте ліберальні в отриманому ".

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

Як щодо вмісту 204 без вмісту? Це дозволить зробити ваш запит успішно обробленим, але нічого не повертає. Це все ще "успіх", але дозволяє вам побачити, чи є у вас результати лише на основі коду статусу.

Якщо URL-адреса представляє ресурс, який ніколи не існував, повернення 404 Не знайдено

Якщо URL-адреса являє собою ресурс, який є порожнім списком, поверніть порожній список і 200 ОК.

Приклад:

{
  total: 0,
  items: []
}

Якщо URL-адреса представляє ресурс, який існував, повертайте 410 Gone.

Щодо діалогу Lego Stormtrooper:

Alien: Computer, please tell me all planets that humans inhabit. GET /planets?inhabitedBy=humans

Computer: 200 OK. { total: 1, items:[{name:'Earth'}] }

Alien: Computer, please tell me about Earth. GET /planets/earth

Computer: 200 OK. {name:'Earth', status: 'Mostly Harmless'}

Alien: Computer, please tell me about all planets humans inhabit, outside the asteroid belt. GET /planets?inhabitedBy=humans&distanceFromSun=lots

Computer: 200 OK. {total:0, items:[] }

Alien: Computer, please destroy Earth. DELETE /planets/earth

Computer: 204 No Content. (or 202 Accepted if it takes some time to destroy Earth)

Alien: Computer, please tell me about Earth. GET /planets/earth

Computer: 410 Gone

Alien: Computer, please tell me all planets that humans inhabit. GET /planets?inhabitedBy=humans

Computer: 200 OK 0 {total: 0, items:[] }

Alien: Victory for the mighty Irken Empire!

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

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

Я також погоджуюся з точкою зору Андреса Ф., що 500 є доцільним, оскільки дерево має існувати. На практиці, хоча, я люблю розділяти помилки сервера на дві категорії. Щось несподіване пішло не так, а те, що я практично можу перевірити, пішло не так. Це призводить до отримання таких кодів статусу,

• 200 - Все добре
• 404 - Неправильний URL
• 409 - Щось пішло не так
• 500 - на сервері сталася несподівана помилка

У вашому конкретному випадку ви можете перевірити, чи існує дерево чи немає на стороні сервера, а якщо його немає, то поверніть 409. Це очікувана помилка (ви знаєте, що це може статися, ви можете перевірити її і т.д.) . 409 конфлікт - це лише мої особисті переваги, 5xx також може бути доречним, якщо ви можете сісти і вирішити це зі своєю командою.

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

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

З іншого боку, якщо це загальнодоступний API, дотримання якомога ближче специфікацій було б важливішим, щоб уникнути плутанини серед спільноти.

Здійснивши тангенціальний удар при цьому: Якщо людина врешті-решт використовує API (через GUI), я б запропонував зробити все, що полегшує життя кінцевому користувачеві. Відсутність дерева, коли воно має існувати, є помилкою "Невідповідність моделі домену". Системна помилка - це коли у вас не вистачало пам'яті або виникла якась інша системна помилка. Тому повертати 5хх недоцільно. Як вже згадувалося кількома людьми вище, 4xx може бути доречним, якби саме дерево мало власний URI, що тут не так. Але ось що 404 каже клієнту: ви можете намагатися знову і знову, поки не отримаєте щось назад. Якщо ви повернули 200, ви можете повернути достатню діагностику назад користувачеві або користувачеві агенту, щоб користувальницький агент міг відображати меааж, щоб користувач перестав повторювати спроби і просто підтримував підтримку контактів. З іншого боку, якщо цей API призначений лише для систем,