REST API error return good practices [закрыто]
Я ищу руководство по передовой практике, когда речь заходит о возврате ошибок из REST API. Я работаю над новым API, поэтому я могу взять его в любом направлении прямо сейчас. Мой тип контента-XML на данный момент, но я планирую поддерживать JSON в будущем.
теперь я добавляю некоторые случаи ошибок, например, клиент пытается добавить новый ресурс, но превысил свою квоту хранения. Я уже обрабатываю некоторые случаи ошибок с кодами состояния HTTP (401 для аутентификации, 403 для авторизация и 404 для простого плохого запроса URI). Я просмотрел благословенные коды ошибок HTTP, но ни один из диапазона 400-417 не кажется правильным сообщать о конкретных ошибках приложения. Поэтому сначала у меня возникло искушение вернуть мою ошибку приложения с 200 OK и конкретной полезной нагрузкой XML (т. е. Заплатите нам больше, и вы получите необходимое вам хранилище! но я перестал об этом думать и вроде бы намылился (/пожимает плечами в ужасе). Кроме того, похоже, что я разделяю ответы на ошибки на отдельные случаи, так как некоторые из них являются http управляемый код состояния и другие управляются содержанием.
Так что же такое отраслевые рекомендации? Передовая практика (пожалуйста, объясните почему!) а также, с точки зрения клиента pov, какая обработка ошибок в REST API упрощает жизнь для клиентского кода?
12 ответов:
поэтому сначала у меня возникло искушение вернуть мою ошибку приложения с 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 в зависимости от различных случаев ошибок.) Впрочем, покоя полиции нет. Ты можешь делать все, что хочешь. Я видел гораздо более вопиющие Аписы без отдыха, которые называются " 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, если необходимый.
документ...
помните, что существует больше кодов состояния, чем те, которые определены в HTTP / 1.1 RFC, реестр IANA находится в http://www.iana.org/assignments/http-status-codes. для случая, который вы упомянули код состояния 507 звучит правильно.
как указывали другие, наличие объекта ответа в коде ошибки совершенно допустимо.
помните, что ошибки 5xx являются серверными, а также клиент не может ничего изменить в своем запросе, чтобы сделать запрос проходным. Если квота клиента превышена, это определенно не ошибка сервера, поэтому 5xx следует избегать.
Я знаю, что это очень поздно для партии, но теперь, в 2013 году, у нас есть несколько типов носителей для обработки ошибок в общей распределенной (RESTful) моде. В разделе "донгов.ошибка", application / vnd.ошибка+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. Они уже являются установленными универсальными кодами, передающими статус ответа, и поэтому, чтобы быть действительно спокойными, приложения должны использовать эту структуру для передачи статуса ответа.
отправка ответа об ошибке в конверте HTTP 200 вводит в заблуждение, и заставляет клиента (потребителя api) анализировать сообщение, скорее всего, нестандартным или проприетарным способом. Это также не эффективно - вы заставите своих клиентов анализировать полезную нагрузку HTTP каждый раз, чтобы понять "реальный" статус ответа. Это увеличивает обработку, увеличивает задержку и создает среду, в которой клиент может совершать ошибки.
моделирование вашего api на существующих "лучших практиках" может быть способом пойти. Например, вот как Twitter обрабатывает коды ошибок https://developer.twitter.com/en/docs/basics/response-codes
пожалуйста, придерживайтесь семантики протокола. Используйте 2xx для успешных ответов и 4xx , 5xx для ответов на ошибки - будь то ваши бизнес-исключения или другие. Если бы использование 2xx для любого ответа было предполагаемым вариантом использования в протоколе, у них не было бы других кодов состояния в первую очередь.
Не забывайте об ошибках 5xx, а также для ошибок приложений.
в этом случае как насчет 409 (конфликт)? Это предполагает, что пользователь может устранить проблему, удалив сохраненные ресурсы.
в противном случае 507 (не совсем стандартный) также может работать. Я бы не использовал 200, если вы не используете 200 для ошибок в целом.
Comments