Помилка REST API повертає добрі практики [закрито]

Я шукаю вказівки щодо передового досвіду щодо повернення помилок з REST API. Я працюю над новим API, тому зараз я можу взяти його в будь-якому напрямку. На даний момент моїм типом вмісту є XML, але я планую підтримувати JSON у майбутньому.

Зараз я додаю деякі випадки помилок, наприклад, наприклад, клієнт намагається додати новий ресурс, але перевищив його квоту на зберігання. Я вже обробляю певні випадки помилок з кодами статусу HTTP (401 для аутентифікації, 403 для авторизації та 404 для URI-адрес простого неправильного запиту). Я переглянув блаженні коди помилок HTTP, але жоден із діапазонів 400-417 не здається правильним повідомляти про додаткові помилки. Тож спочатку я спокусився повернути свою помилку програми з 200 ОК та конкретним корисним навантаженням XML (тобто. Платіть нам більше, і ви отримаєте потрібне вам сховище!), Але я перестав думати про це, і, здається, мильний (/ від жаху знизати плечима). Крім того, я відчуваю, що я розбиваю відповіді на помилки на окремі випадки, оскільки деякі керуються кодом статусу http, а інші керуються вмістом.

То що таке галузеві рекомендації? Належні практики (будь-ласка, поясніть, чому!), А також, від клієнта pov, який вид обробки помилок в API REST полегшує життя коду клієнта?

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

Я б не повернув 200, якщо справді не було нічого поганого в запиті. З RFC2616 , 200 означає "запит вдався".

Якщо квота на зберігання клієнта була перевищена (з будь-якої причини), я поверну 403 (Заборонено):

Сервер зрозумів запит, але відмовляється його виконувати. Авторизація не допоможе, і запит НЕ повинен повторюватися. Якщо метод запиту не був HEAD і сервер бажає оприлюднити, чому запит не був виконаний, він ДОЛЖЕН описувати причину відмови в організації. Якщо сервер не бажає надавати цю інформацію клієнту, замість цього може використовуватися код статусу 404 (Не знайдено).

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

Які ще конкретні умови помилки ви мали на увазі?

Чудовий ресурс для вибору правильного коду помилки HTTP для вашого API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Уривок із статті:

З чого почати:

2XX / 3XX:

4XX:

5XX:

Основним вибором є те, чи хочете ви розглядати код статусу HTTP як частину свого REST API чи ні.

Обидва способи працюють добре. Я погоджуюся, що, строго кажучи, одна з ідей REST полягає в тому, що ви повинні використовувати код статусу HTTP як частину свого API (поверніть 200 або 201 для успішної операції та 4xx або 5xx залежно від різних випадків помилок.) Однак , поліції REST немає. Ви можете робити те, що хочете. Я бачив набагато більш кричущі API, які не є REST, називаються "RESTful".

На даний момент (серпень, 2015 р.) Я рекомендую використовувати код статусу HTTP як частина свого API. Зараз набагато простіше бачити зворотний код при використанні фреймворків, ніж це було раніше. Зокрема, зараз простіше бачити випадок повернення без 200 та сукупність не 200 відповідей, ніж це було раніше.

Код статусу HTTP є частиною вашої програми

1. Вам потрібно буде ретельно підбирати 4xx-коди, які відповідають вашим умовам помилок. Ви можете включити повідомлення про відпочинок, xml або в простому тексті як корисне навантаження, що включає під-код та описовий коментар.

2. Клієнтам потрібно буде використовувати програмне забезпечення, яке дозволяє отримувати код статусу на рівні HTTP. Зазвичай зробити це можливо, не завжди прямо.

3. Клієнтам доведеться розрізняти коди статусу HTTP, які вказують на помилку зв'язку, та ваші власні коди статусу, які вказують на проблему на рівні програми.

Код статусу HTTP НЕ є частиною вашої програми

1. Код статусу HTTP завжди буде 200, якщо ваша програма отримала запит, а потім відповіла (як випадки успіху, так і помилки)

2. ВСІ ваші відповіді повинні містити інформацію про «конверт» або «заголовок». Зазвичай щось на зразок:

   envelope_ver: 1.0
   статус: # використовувати будь-які коди, які вам подобаються. Зарезервуйте код для успіху.
   msg: "ok" # рядок людини, що відображає код. Корисно для налагодження.
   data: ... # Дані відповіді, якщо такі є.

3. Цей спосіб може бути простішим для клієнтів, оскільки статус для відповіді завжди знаходиться в одному і тому ж місці (не потрібні підкоди), немає обмежень на коди, не потрібно отримувати код статусу на рівні HTTP.

Ось публікація з подібною ідеєю: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Основні питання:

1. Обов’язково введіть номери версій, щоб ви могли пізніше змінити семантику api за потреби.

2. Документ ...

Пам'ятайте, що існує більше кодів статусу, ніж визначених у RFC HTTP / 1.1, реєстр IANA знаходиться за адресою http://www.iana.org/assignments/http-status-codes . У випадку, коли ви згадали код статусу 507, звучить правильно.

Як зазначали інші, наявність сутності відповіді в коді помилки цілком допустимо.

Пам'ятайте, що помилки 5xx є стороною сервера, він також не може нічого змінити на свій запит, щоб передати запит. Якщо квота клієнта буде перевищена, це однозначно не є помилкою сервера, тому слід уникати 5xx.

Існує два види помилок. Помилки програми та помилки HTTP. Помилки HTTP полягають у тому, щоб ваш обробник AJAX знав, що все пішло нормально і не слід його використовувати ні для чого іншого.

5xx помилка серверу

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Успіх

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Однак, як ви розробляєте помилки програми, залежить від вас. Переповнення стека, наприклад , посилає об'єкт з response, dataі messageвластивостями. Я вважаю, що відповідь містить trueабо falseвказує на те, що операція пройшла успішно (зазвичай це стосується операцій запису). Дані містять корисну навантаження (зазвичай для операцій з читання), а повідомлення містить будь-які додаткові метадані або корисні повідомлення (наприклад, повідомлення про помилки, коли responseє false).

Я знаю, що це дуже пізно для вечірки, але зараз, у 2013 році, у нас є декілька типів засобів масової інформації, щоб висвітлювати обробку помилок у розповсюдженому (RESTful) способі. Див. "Vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) та "Інформація про проблему для HTTP API", застосунок / проблема + json ( https: // інструменти. ietf.org/html/draft-nottingham-http-problem-05 ).

Домовились. Основна філософія REST - використання веб-інфраструктури. Коди статусу HTTP - це система обміну повідомленнями, яка дозволяє сторонам спілкуватися один з одним без збільшення навантаження HTTP. Вони вже встановили універсальні коди, що передають статус відповіді, і тому, щоб бути по-справжньому RESTful, програми повинні використовувати цю рамку для передачі статусу відповіді.

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

Моделювання вашого api на існуючих "кращих практиках" може бути дорогою. Наприклад, ось як Twitter обробляє коди помилок https://developer.twitter.com/en/docs/basics/response-codes

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

Не забувайте також про помилки 5xx, а також про помилки програми.

У цьому випадку, що з 409 (конфлікт)? Це передбачає, що користувач може усунути проблему, видаливши збережені ресурси.

Інакше 507 (не зовсім стандартно) також може працювати. Я б не використовував 200, якщо ви взагалі не використовуєте 200 для помилок.

Якщо клієнтська квота перевищена, це помилка сервера, уникайте 5xx у цьому випадку.