Код кода ошибки для API

Каков хороший выбор для шаблона ответа кода ошибки API?

Вместо использования разных кодов, указывающих на разные типы ошибок

100001 // username not provided
100002 // password not provided
100003 // password too short
...

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

20000
20001
20004
20015

Есть ли другие рекомендации?

+5
источник поделиться
5 ответов

Рекомендация IETF (орган интернет-стандартов) использует метод application/problem + json mediatype.

Примечательно, что они не используют случайные числа, они используют строки (в частности, uris) для выявления ошибок.

Это субъективный вопрос, но даже если вы не используете их формат, я бы утвердил, что username-not-provided лучше всего по 100001.

+6
источник

По моему опыту разработки и использования веб-сервисов я обнаружил, что стратегия использования комбинации кодов состояния HTTP верхнего уровня и кодов ошибок API более низкого уровня работает достаточно хорошо. Обратите внимание, что коды ошибок API нижнего уровня не обязательно должны быть целыми числами, но могут быть любыми перечислениями. Для общеизвестного публичного примера AWS Simple Email Service (SES) использует эту стратегию использования кодов состояния HTTP и кодов ошибок уровня API. Здесь вы можете увидеть пример кода ошибки для SES. Обратите внимание, что хотя SES использует полезную нагрузку на ошибку ответа XML, эта стратегия одинаково хорошо работает для полезных данных JSON.

По моему опыту, есть несколько вещей, которые вам нужно иметь в виду при использовании этой стратегии:

  1. Стремитесь вернуть правильный HTTP-код ответа: HTTP - это вездесущий протокол и, без сомнения, понимается вашим веб-контейнером. Его коды ответов естественно вписываются в веб-службы REST. Таким образом, используйте это! Если ваша веб-служба сталкивается с условием ошибки, вы должны сделать все возможное, чтобы вернуть правильный код состояния HTTP, в контексте которого имеет смысл код ошибки API. Одна из моих самых больших головных болей при отладке проблем с веб-службами возникает, когда разработчики просто безоговорочно бросают произвольные (обычно исполняемые) исключения, резервные копии стека. В результате все возвращается к вызывающему абоненту как код статуса HTTP 500 (Internal Server Error), даже если это не так (например, клиент отправляет данные об мусоре, и сервер просто не может его обработать. вы можете спроектировать для включения:
    • 400 Bad Request: есть проблема с запросом клиента. Обратите внимание, что эта ошибка используется не только для синтаксиса JSON в запросе POST, но также является законным кодом ответа для семантических проблем (т.е. Полезная нагрузка запроса JSON соответствует предписанной схеме, но возникла проблема с данные в полезной нагрузке, такие как число, отрицательное, когда оно должно быть только положительным).
    • 401 Unauthorized: учетные данные вызывающего абонента были недействительными (например, ошибка авторизации).
    • 403 Запрещено: учетные данные вызывающего абонента действительны, но их уровень доступа недостаточен для доступа к ресурсу (например, ошибка аутентификации).
    • 404 Not Found: Ресурс URL-адреса не существует.
    • 500 Внутренняя ошибка сервера: что-то плохое произошло внутри самого сервера, эта ошибка может быть любой.
    • 502 Bad Gateway: произошла ошибка при вызове службы нисходящего потока.
    • 503 Service Unavailable: полезный код ответа для того, когда вы забиваете тонну "счастливых" клиентов, которые непреднамеренно DDOS'у вашего сервиса.
    • 504 Тайм-аут шлюза: как и код состояния 502, но указывает на тайм-аут вместо фактической ошибки с нисходящей службой, как таковой.
  2. Коды ответов HTTP - это коды верхнего уровня, а коды ошибок API имеют смысл только в этом контексте: я имею в виду, что ваши коды ошибок API имеют смысл только для определенных кодов ответа HTTP. Например, в таблице кодов ошибок SES каждый код ошибки привязан только к одному коду ответа HTTP (S). Коды ошибок ConfigurationSetDoesNotExist и InvalidParameterValue имеют смысл только тогда, когда SES возвращается 400 Bad Request и было бы InvalidParameterValue возвращать эти коды состояния, когда возвращается 500 Internal Server Error. Аналогичным образом, если вы пишете веб-службу, которая FooDownstreamServiceTimedOut нисходящими службами и базами данных, у вас может быть FooDownstreamServiceTimedOut ошибки FooDownstreamServiceTimedOut который вы FooDownstreamServiceTimedOut кодом состояния HTTP 504 Gateway Timeout когда нисходящий вызов веб-службы, приуроченный к веб-службе Foo, Возможно, у вас также есть MyDatabaseError ошибки MyDatabaseError который вы MyDatabaseError кодом состояния HTTP с 500 Internal Server Error когда ваш запрос во внутреннюю БД завершится с ошибкой.
  3. Имейте единую схему кода ошибки независимо от кодов состояния. Ваши клиенты должны иметь возможность обрабатывать ваш код ошибки программным путем. Таким образом, он должен соответствовать определенной схеме. В идеале ваша схема кода ошибки API должна содержать код ошибки (то есть имя или идентификатор и т.д.). Вероятно, вы также захотите включить описание кода ошибки на естественном языке и идентификатор/идентификатор GUID запроса, на который вы отвечаете. Пример схемы ошибки см. В этом примере ответа и схемы AWS SES. Кроме того, вы также можете рассмотреть возможность возврата идентификатора клиента в ответ. Это так же важно для вашего же блага, как и клиент, поскольку он может помочь вам разобраться в данных, чтобы увидеть, как один конкретный клиент получает избыток определенных ошибок против ваших других клиентов.
  4. Подумайте о возврате описаний кода ошибок в ответе на естественный язык в ответе: чтобы упростить работу с вашими клиентами, вам может потребоваться не просто вернуть код ошибки в полезную нагрузку ошибки, но также и описание на естественном языке. Такое поведение может немедленно помочь запутавшимся и занятым инженерам, которые действительно не заботятся о том, что много о вашем обслуживании быстро диагностируют, что происходит, чтобы они могли решить проблему как можно скорее. btw, позволяя инженерам быстро диагностировать проблемы с вашим сервисом, увеличивает значительную метрику "безотказной работы", о которой, без сомнения, заботятся ваши клиенты и менеджеры.
  5. Не чувствуйте себя обязанным использовать целые числа, вместо этого используйте перечисления. Понятие "коды ошибок" вызывает в воображении изображения устаревших технологий и кодовых книг, в которых вам приходилось искать то, что означало ошибку. Он возник из-за программирования темных веков, когда инженерам необходимо было вместить все возможные ошибки в байты пространства или полубайт или что-то еще. Эти дни ушли, и ваш код ошибки может быть строкой, вероятно, без какого-либо значимого влияния на производительность. Вы могли бы также воспользоваться преимуществами и сделать код ошибки значимым, как средство сохранения вещей.
  6. Возвращайте информацию клиентам, которые, возможно, потребуется отлаживать, но помните о безопасности: если возможно, верните любую информацию об отладке, которая может понадобиться вашим клиентам. Однако, если ваш сервис потенциально имеет дело с конфиденциальной информацией, такой как номера кредитных карт и т.п., Вы, вероятно, не хотите передавать эту информацию по очевидным причинам.

Надеюсь, это поможет.

+5
источник

Я бы сказал, что это сильно зависит от того, какой API вы предоставляете.

Я должен всегда включать поле под названием ack или что-то подобное в каждом ответе, который имеет три состояния: failure, warning, success. Успех, очевидно, - все пошло хорошо. При предупреждении запрос прошел, и JSON будет содержать ожидаемый результат, но он также будет содержать строку warning или даже лучше, если могут возникнуть несколько предупреждений о массиве, который называется errors который состоит из нескольких объектов, содержащих code, string и type. Этот массив также будет возвращен в случае failure, и ничего, кроме этого массива.

Массив содержит один объект за ошибку или предупреждение, имеющий код (я бы предложил перейти к вашей первоначальной идее 10001, 10002,...) и строку, объясняющую ошибку в очень короткой фразе (например, Username contains invalid characters). type - это либо error либо warning, которое полезно в случае failure ack, который содержит не только ошибки, но и предупреждения.

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

Это также позволяет легко выводить предупреждения и ошибки конечному пользователю, а не только разработчикам. Используя мою идею с вызовом API для получения информации об ошибке, разработчики, использующие ваш API, могут легко предоставить полную информацию об ошибках конечным пользователям, когда это необходимо (включая причины/исправления/все, что вам подходит).

0
источник

Вместо того, чтобы писать свой собственный стандарт API с нуля, используйте один из уже доступных, например стандарт JSON API:

Если вы когда-либо спорили с вашей командой о том, как ваши отклики JSON должны быть отформатированы, JSON API может быть вашим средством против bikeshedding.

Следуя общим соглашениям, вы можете повысить производительность, воспользоваться обобщенными инструментами и сосредоточиться на том, что важно: ваше приложение.

Клиенты, созданные на основе JSON API, могут использовать преимущества своих функций для эффективного кэширования ответов, иногда полностью исключая сетевые запросы.

Если вы решите пойти с JSON API, у него есть раздел, посвященный ошибкам и несколько примеров ошибок.

0
источник

На протяжении многих лет многие компании-разработчики создавали такие вещи, как битмаски для ошибок, поэтому они могут кодировать несколько переменных внутри ошибки:

000 - all ok
001 - something failed with X
010 - something failed with Y
011 - something failed with X and Y
100 - something failed with Z
101 - something failed with X and Z

Ограничение заключается в том, что это ограничивает пространство ошибок на столько байтов, которые вы определяете при кодировании, например 16 или 32 возможных комбинаций, этого может быть достаточно для вас или нет.

Вы видите, что это распространено в COM+ https://docs.microsoft.com/en-us/windows/desktop/com/com-error-codes-1

Надеюсь, это поможет.

0
источник

Посмотрите другие вопросы по меткам или Задайте вопрос