Ошибка API REST возвращает хорошие практики [закрыто]

Я ищу руководство по передовым методам, когда дело доходит до возврата ошибок из REST API. Я работаю над новым API, поэтому я могу использовать его в любом направлении прямо сейчас. В настоящее время мой тип контента - XML, но в будущем я планирую поддерживать JSON.

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

Так, каковы отраслевые рекомендации? Хорошая практика (пожалуйста, объясните почему!), А также, от клиента, что обработка ошибок в REST API облегчает жизнь клиентскому коду?

Поэтому сначала я хотел вернуть ошибку моего приложения с 200 OK и определенной полезной нагрузкой 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 в зависимости от различных случаев ошибки.) Однако ОТСУТСТВУЕТ полиция. Ты можешь делать, что хочешь. Я видел гораздо более вопиющие API без REST, называемые RESTful.

На данный момент (август 2015 г.) я рекомендую использовать код статуса HTTP как часть вашего API. Теперь намного проще увидеть код возврата при использовании фреймворков, чем это было в прошлом. В частности, теперь легче увидеть случай возврата, не связанный с 200, и массу ответов, не связанных с 200, чем это было в прошлом.

Код статуса HTTP является частью вашего API

1. Вам нужно будет тщательно выбрать коды 4xx, которые соответствуют вашим условиям ошибки. В качестве полезной нагрузки можно добавить сообщение отдыха, XML или текстовое сообщение, которое включает субкод и описательный комментарий.

2. Клиенты должны будут использовать программную среду, которая позволяет им получить код состояния уровня HTTP. Обычно выполнимый, не всегда прямой.

3. Клиенты должны будут различать коды состояния HTTP, которые указывают на ошибку связи, и ваши собственные коды состояния, которые указывают на проблему на уровне приложения.

Код статуса HTTP НЕ является частью вашего API

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», application / problem + json ( https: // tools. 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 в этом случае.