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

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

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

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

    12 Solutions collect form web for “Ошибка API REST возвращает хорошие практики”

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

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

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

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

    Это говорит клиенту, что запрос был в порядке, но что он не удался (что-то 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, которые соответствуют вашим условиям ошибки. Вы можете включить сообщение rest, xml или plaintext как полезную нагрузку, которая включает в себя субкод и описательный комментарий.

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

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

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

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

    2. ВСЕ ваши ответы должны включать информацию «конверт» или «заголовок». Обычно что-то вроде:

        envelope_ver: 1.0
       status: # использовать любые коды, которые вам нравятся.  Зарезервируйте код для успеха. 
       msg: "ok" # Человеческая строка, которая отражает код.  Полезно для отладки.
       data: ... # Данные ответа, если они есть. 
    3. Этот метод может быть проще для клиентов, поскольку статус ответа всегда находится в одном и том же месте (без субкодов), без ограничений на коды, нет необходимости извлекать код состояния уровня HTTP.

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

    Главные проблемы:

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

    2. Документ…

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

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

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

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

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

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

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

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

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

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

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

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

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

    Давайте будем гением компьютера.