Який код статусу HTTP повернути, якщо кілька дій закінчуються різними статусами?

Я будую API, де користувач може попросити сервер виконати кілька дій в одному HTTP-запиті. Результат повертається у вигляді масиву JSON з одним записом на дію.

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

Якби був один запит на дію, я б повертав коди статусу 200, 422 та 500 відповідно. Але тепер, коли є лише один запит, який код статусу я повинен повернути?

Деякі варіанти:

• Завжди повертайте 200 і дайте більш детальну інформацію в організмі.
• Можливо, дотримуйтесь наведеного правила лише тоді, коли в запиті є кілька дій?
• Може повернути 200, якщо всі запити будуть успішними, інакше 500 (або якийсь інший код)?
• Просто використовуйте один запит на дію та приймайте додаткові накладні витрати.
• Щось зовсім інше?

Коротка, пряма відповідь

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

Довга філософська відповідь

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

З урахуванням вищесказаного, і без сміливості перетворити цю відповідь на довгий сумнівний посібник, наступна схема URI, яка відповідає підходу до управління ресурсами:

• /tasks
  • GET перелічує всі завдання, що страждають на сторінку
  • POST додає єдине завдання
• /tasks/task/[id]
  • GET відповідає на об’єкт стану одного завдання
  • DELETE скасовує / видаляє завдання
• /tasks/groups
  • GET перелічує всі групи завдань, що страждають на сторінки
  • POST додає групу завдань
• /tasks/groups/group/[id]
  • GET відповідає станом групи завдань
  • DELETE скасовує / видаляє групу завдань

Ця структура говорить про ресурси, а не про те, що з ними робити. Те, що робиться з ресурсами, - це турбота про іншу службу.

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

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

Деякі приклади використання такої схеми URI

Виконання одного завдання та відстеження прогресу:

• POST /tasks із завданням виконати
  • GET /tasks/task/[id]поки об'єкт відповіді не completedотримає позитивного значення під час показу поточного стану / прогресу

Виконання одного завдання та очікування його завершення:

• POST /tasks із завданням виконати
  • GET /tasks/task/[id]?awaitCompletion=trueпоки не completedотримає позитивного значення (швидше за все, має таймаут, через що це слід циклічно)

Виконання групи завдань та відстеження прогресу:

• POST /tasks/groups з групою завдань для виконання
  • GET /tasks/groups/group/[groupId]поки completedвластивість об'єкта відповіді не має значення, показуючи стан індивідуального завдання (наприклад, 3 завдання, виконані з 5, наприклад)

Запит на виконання групи завдань та очікування її завершення:

• POST /tasks/groups з групою завдань для виконання
  • GET /tasks/groups/group/[groupId]?awaitCompletion=true до тих пір, поки не відповідає з результатом, який позначає завершення (ймовірно, має час очікування, тому його слід петляти)

Моє голосування було б розділити ці завдання на окремі запити. Однак якщо турбота занадто велика, то я зіткнувся з кодом відповіді HTTP 207 - Multi-Status

Скопіюйте / вставте з цього посилання:

Відповідь з декількома статусами передає інформацію про кілька ресурсів у ситуаціях, коли може бути доречним кілька кодів статусу. Типовим тілом відповіді за замовчуванням є статус HTTP тексту / xml або програми / xml з кореневим елементом 'мультистатус'. Подальші елементи містять коди статусу серії 200, 300, 400 та 500, сформовані під час виклику методу. Коди статусу 100 серій НЕ БУДЬТЕ записуватися в XML-елемент 'відповіді'.

Хоча «207» використовується як загальний код статусу відповіді, одержувачеві необхідно проконсультуватися зі змістом органу відповіді з багатоступеневою інформацією для отримання додаткової інформації про успішність або невдачу виконання методу. Відповідь МОЖЕ бути використана для успіху, часткового успіху, а також у ситуаціях невдач.

Хоча багатостандартність - це варіант, я б повернув 200 (Все добре), якщо всі запити були успішними та помилка (500 чи, можливо, 207) в іншому випадку.

Стандартний корпус зазвичай повинен бути 200 - все працює. І клієнти повинні лише перевірити це. І лише якщо стався випадок помилки, ви можете повернути 500 (або 207). Я думаю, що 207 є правильним вибором у випадку принаймні однієї помилки, але якщо ви бачите весь пакет як одну транзакцію, ви також можете надіслати 500. - Клієнт захоче інтерпретувати повідомлення про помилку в будь-якому випадку.

Чому б не завжди надсилати 207? - Тому що стандартні корпуси повинні бути простими та стандартними. Хоча виняткові випадки можуть бути винятковими. Клієнт повинен лише прочитати орган реагування та прийняти подальші складні рішення, якщо цього вимагає виняткова ситуація.

Одним із варіантів було б завжди повертати код статусу 200, а потім повертати конкретні помилки у вашому документі JSON. Саме так розроблені деякі API (вони завжди повертають код статусу 200 і розсилають помилку в тілі). Докладніше про різні підходи див. У розділі http://archive.oreilly.com/pub/post/restful_error_handling.html

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

Проблема з спробою надіслати кілька дій в одному запиті полягає саме в тому, що кожна дія повинна мати власний "статус"

Дивлячись на імпорт CSV (я не дуже знаю, про що йдеться в ОП, але це проста версія). Розмістіть CSV та отримайте 206. Потім пізніше CSV можна імпортувати, і ви можете отримати статус імпорту за допомогою GET (200) проти URL-адреси, що показує помилки в рядку.

POST /imports/ -> 206
GET  /imports/1 -> 200
GET  /imports/1/errors -> 200 -> Has a list of errors

Цей же візерунок може бути застосований до багатьох операцій партії

POST /operations/ -> 206
GET  /operations/1 -> 200
GET  /operations/1/errors -> 200 - > Has a list of errors.

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

Тут уже багато хороших відповідей, але один аспект відсутній:

Який контракт очікують ваші клієнти?

HTTP-коди повернення повинні вказувати на принаймні відмінність успіху / невдачі і, таким чином, грати роль "винятку бідної людини". Тоді 200 означає "договір повністю виконаний", а 4xx або 5xx вказують на невиконання.

Наївно, я б очікував, що у договорі вашого запиту на кілька дій буде "виконувати всі мої завдання", і якщо одна з них не вдасться, то запит не був (повністю) успішним. Як правило, я як клієнт розумів 200 як "все нормально", а коди з сімей 400 і 500 змушують мене думати про наслідки (часткової) відмови. Отже, використовуйте 200 для "всіх виконаних завдань" і 500 плюс описову відповідь у разі часткової відмови.

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

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

Кінцевий важливий аспект: як ви повідомляєте про своє контрактне рішення своїм клієнтам? Наприклад, у Java, я б використовував назви методів типу "doAll ()" або "tryToDoAll ()". У HTTP ви можете відповідно називати URL-адреси кінцевих точок, сподіваючись, що ваші клієнтські розробники побачать, прочитали та зрозуміли іменування (я не став би на це ставити). Ще одна причина вибору договору як мінімум сюрпризу.

Відповідь:

Просто використовуйте один запит на дію та приймайте додаткові накладні витрати.

Код статусу описує стан однієї операції. Тому має сенс проводити одну операцію на запит.

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

HTTP / 1.1 та HTTP / 2 значно знизили накладні витрати HTTP-запитів. Я вважаю, що існує дуже мало ситуацій, коли доцільне отримання незалежних запитів доцільно.

Це сказав:

(1) Ви можете зробити кілька модифікацій за допомогою запиту PATCH ( RFC 5789 ). Однак це вимагає, щоб зміни не були незалежними; їх застосовують атомно (все або нічого).

(2) Інші вказали на код 207 багатозначного статусу. Однак це визначено лише для WebDAV ( RFC 4918 ), розширення HTTP.

Код статусу 207 (Multi-Status) забезпечує статус для декількох незалежних операцій (для отримання додаткової інформації див. Розділ 13).

...

Відповідь з декількома статусами передає інформацію про кілька ресурсів у ситуаціях, коли може бути доречним кілька кодів статусу. Елемент кореня [XML] 'мультистатус' містить нульовий або більше елементів 'відповіді' у будь-якому порядку, кожен з інформацією про окремий ресурс.

Відповідь XML 207 WebDAV була б такою ж дивною, як і качка в API не WebDAV. Не робіть цього.

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

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