Ошибка API REST возвращает рекомендации [закрыто]

Question

Ошибка API REST возвращает рекомендации [закрыто]

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

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

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

554

http rest web-services

автор: Michael Freidgeim

12 ответов

автор: Rich Apodaca · Accepted Answer · 2009-06-03 04:08:13

поэтому сначала у меня был соблазн вернуть мою ошибку приложения с 200 OK и определенной полезной нагрузкой XML (т. е. Заплатите нам больше, и вы получите необходимое вам хранилище!) но я перестал думать об этом, и мне кажется, что мыльный (/пожимает плечами в ужасе).

Я бы не вернул 200, если бы действительно не было ничего плохого в запросе. От адресу rfc2616, 200 означает " запрос удался."

если квота хранения клиента превышена (для по какой причине), я бы вернул 403 (запрещено):

сервер понял запрос, но отказывается выполнять его. Разрешение не поможет, и запрос не должен повторяться. Если метод запроса не был HEAD и сервер желает обнародовать, почему запрос не был выполнен, он должен описать причину отказа в сущности. Если сервер не желает делать эту информацию доступной для клиента, код состояния 404 (не найден) может используйте вместо этого.

это говорит клиенту, что запрос был в порядке, но что он не удался (что-то 200 не делает). Это также дает вам возможность объяснить проблему (и ее решение) в тексте ответа.

какие еще конкретные условия ошибки вы имели в виду?

автор: Omar Ali · Accepted Answer · 2018-02-17 19:50:28

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

отрывок из статьи:

С чего начать:

2ХХ/3 * Х:

4XX:

С кодом 5xx:

автор: Larry K · Accepted Answer · 2016-07-21 11:01:06

основной выбор-хотите ли вы рассматривать код состояния HTTP как часть вашего REST API или нет.

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

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

код состояния HTTP является частью вашего api

вам нужно будет тщательно подобрать 4xx коды это соответствует вашим условиям ошибки. Вы можете включить сообщение rest, xml или открытый текст в качестве полезной нагрузки, которая включает под-код и описательный комментарий.
клиенты должны будут использовать программную структуру, которая позволяет им получить код состояния на уровне HTTP. Обычно делают-умеют, не всегда прямолинейны.
клиенты должны будут различать коды состояния HTTP, указывающие на ошибку связи, и ваши собственные коды состояния это указывает на проблему уровня приложения.

код состояния HTTP не является частью вашего api

код состояния HTTP всегда будет 200, если ваше приложение получило запрос, а затем ответило (как в случае успеха, так и в случае ошибки)

все ваши ответы должны включать информацию" конверт "или" заголовок". Обычно что-то вроде:

envelope_ver: 1.0
status:  # use any codes you like. Reserve a code for success. 
msg: "ok" # A human string that reflects the code. Useful for debugging.
data: ...  # The data of the response, if any.

этот метод может быть проще для клиентов, так как статус ответа всегда находится в одном и том же месте (не требуется подкодов), никаких ограничений на коды, нет необходимости получать код состояния HTTP-уровня.

вот сообщение с аналогичной идеей:http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

основные вопросы:

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

автор: Julian Reschke · Accepted Answer · 2014-10-01 07:00:15

помните, что существует больше кодов состояния, чем те, которые определены в HTTP / 1.1 RFCs, реестр IANA находится вhttp://www.iana.org/assignments/http-status-codes. Для случая, который вы упомянули, код состояния 507 звучит правильно.

автор: SerialSeb · Accepted Answer · 2009-06-04 13:54:39

как указывали другие, наличие объекта ответа в коде ошибки совершенно допустимо.

помните, что ошибки 5xx являются серверными, то есть клиент не может ничего изменить в своем запросе, чтобы сделать запрос. Если квота клиента превышена, это определенно не ошибка сервера, поэтому 5xx следует избегать.

автор: Jørn Wildt · Accepted Answer · 2013-12-18 09:49:52

Я знаю, что это очень поздно для партии, но теперь, в 2013 году, у нас есть несколько типов носителей для обработки ошибок в общей распределенной (RESTful) манере. См. " vnd.ошибка", application / vnd.ошибка+json (https://github.com/blongden/vnd.error) и "сведения о проблеме для HTTP API", application / problem+json (https://tools.ietf.org/html/draft-nottingham-http-problem-05).

автор: aleemb · Accepted Answer · 2009-06-03 09:21:14

есть два вида ошибок. Ошибки приложений и ошибки 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)

однако, как вы разрабатываете свои ошибки приложения действительно зависит от вас. Например, Stack Overflow отправляет объект с response, data и message свойства. Ответ, которому я верю содержит true или false чтобы указать, была ли операция успешной (обычно для операций записи). Данные содержат полезную нагрузку (обычно для операций чтения), а сообщение содержит любые дополнительные метаданные или полезные сообщения (например, сообщения об ошибках, когда response is false).

автор: Kingz · Accepted Answer · 2013-11-21 17:38:01

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

отправка ответа об ошибке в конверте HTTP 200 вводит в заблуждение, и заставляет клиента (потребителя api) анализировать сообщение, скорее всего, нестандартным или проприетарным способом. Это также неэффективно - вы заставите своих клиентов анализировать полезную нагрузку HTTP каждый раз, чтобы понять "реальный" статус ответа. Это увеличивает обработку, добавляет задержку и создает среду для клиента, чтобы совершать ошибки.

автор: Gokul · Accepted Answer · 2018-01-08 04:08:51

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

автор: rahil008 · Accepted Answer · 2016-04-14 06:42:33

пожалуйста, придерживайтесь семантики протокола. Используйте 2xx для успешных ответов и 4xx, 5xx для ответов на ошибки-будь то ваши бизнес-исключения или другие. Если бы использование 2xx для любого ответа было предполагаемым вариантом использования в протоколе, у них не было бы других кодов статуса в первую очередь.

автор: Kathy Van Stone · Accepted Answer · 2009-06-03 15:38:00

Не забывайте об ошибках 5xx, а также для ошибок приложений.

в этом случае как насчет 409 (конфликт)? Предполагается, что пользователь может устранить проблему, удалив сохраненные ресурсы.

в противном случае 507 (не совсем стандартный) также может работать. Я бы не использовал 200, если вы не используете 200 для ошибок в целом.

автор: fixed annuity · Accepted Answer · 2010-05-06 00:02:45

если квота клиента превышена, это ошибка сервера, избегайте 5xx в этом случае.