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

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

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

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

Ответ 1

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

Я бы не возвращал 200, если в запросе не было ничего плохого. Из RFC2616 200 означает, что запрос выполнен успешно.

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

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

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

Какие другие особые ошибки вы имели в виду?

Ответ 2

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

Выдержка из статьи:

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

введите описание изображения здесь

2XX/3XX:

введите описание изображения здесь

4XX:

введите описание изображения здесь

5XX:

введите здесь описание изображения

Ответ 3

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

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

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

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

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

  • Клиентам необходимо будет использовать программную среду, которая позволяет им получить код состояния 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, если это необходимо.

  • Document...

Ответ 4

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

Ответ 5

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

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

Ответ 6

Я знаю, что это очень поздно для партии, но теперь, в 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).

Ответ 7

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

Ответ 8

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

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

Ответ 9

Модифицировать ваш api на существующих "лучших практиках" может быть путь. Например, вот как Twitter обрабатывает коды ошибок https://dev.twitter.com/docs/error-codes-responses

Ответ 10

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

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

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

Ответ 11

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

Ответ 12

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