С тех пор, как я начал работать над Апач APISIX проект, я пытался улучшить свои знания и понимание REST RESTful HTTP API. Для этого я читаю и смотрю следующие источники:

  • Книги. На данный момент заканчиваю Шаблоны проектирования API. Ожидайте отзыв в ближайшее время.
  • YouTube. я бы порекомендовал Канал Эрика Уайльда. Хотя некоторые видео лучше других, все они сосредоточены на API.
  • IETF RFCс. Большинство RFC посвящены не API, а дружелюбный человек составил список те, кто.

Сегодня я хотел бы представить RFC «Сведения о проблеме для HTTP API», он же, RFC 7807.


Проблемы)

Принципы REST предписывают использовать статус HTTP для связи. Для ошибок HTTP определяет два диапазона: ошибки клиента, 4xxи ошибки сервера, 5xx.

Представьте себе банковский API, позволяющий совершать переводы. Это должно потерпеть неудачу, если вы попытаетесь перевести больше средств на свой счет. Пара кодов состояния HTTP может подойти:

  • 400 Bad Request: сервер не может или не будет обрабатывать запрос из-за чего-то, что воспринимается как ошибка клиента.
  • 402 Payment Required: Запрос не может быть обработан, пока клиент не совершит платеж. Однако стандартного соглашения об использовании не существует, и разные организации используют его в других контекстах.
  • 409 Conflict: запрос конфликтует с текущим состоянием целевого ресурса.

Вот первая проблема: коды состояния HTTP были указаны для взаимодействия человека с машиной через браузеры, а не для взаимодействия между машинами через API. Следовательно, выбор кода состояния, который однозначно соответствует варианту использования, редко бывает простым. Для записи, Мартин Фаулер, кажется, предпочитает 409 в нашем случае..

Каким бы ни был код состояния, вторая проблема касается полезной нагрузки ошибки или, точнее, ее структуры. Структура не имеет значения, если одна организация управляет клиентом и поставщиком API. Даже если каждую из них разрабатывает специальная команда, они могут согласоваться. Например, представьте себе мобильное приложение, которое вызывает собственный API.

Однако проблемы возникают, когда команда решает использовать сторонний API. В данном случае важен выбор структуры ответа, поскольку теперь он считается частью контракта: любое изменение поставщика может нарушить работу клиентов. Хуже того, структура, вероятно, отличается от поставщика к поставщику.

Следовательно, стандартизированная структура сообщения об ошибках:

  • Обеспечивает единообразие среди поставщиков
  • Повышает стабильность API


RFC 7807

RFC 7807 направлен на решение проблемы путем предоставления стандартизированной структуры ошибок.

Структура следующая:

Структура сведений о проблеме

RFC описывает поля:

  • "type" (string) — ссылка URI [RFC3986] который определяет тип проблемы. Эта спецификация поощряет то, что при разыменовании она предоставляет удобочитаемую документацию для типа проблемы (напримериспользуя HTML [W3C.REC-html5-20141028]). Когда этот элемент отсутствует, предполагается, что его значение равно "about:blank".
  • "title" (string) — краткое, удобочитаемое описание типа проблемы. Он НЕ ДОЛЖЕН меняться от случая к случаю возникновения проблемы, за исключением целей локализации (например, используя проактивное согласование контента; видеть [RFC7231, Section 3.4]).
  • "status" (number) — ([RFC7231]Раздел 6), созданный исходным сервером для данного возникновения проблемы.
  • "detail" (string) — удобочитаемое объяснение, относящееся к этому возникновению проблемы.
  • "instance" (string) — ссылка URI, которая идентифицирует конкретное возникновение проблемы. Он может давать или не давать дополнительную информацию при разыменовании.

Члены объекта сведений о проблеме

RFC предлагает следующий образец, когда для осуществления банковского перевода необходимо больше средств.

Сведения о проблеме, образец JSON


Пример

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

На шаге 6 я хочу, чтобы пользователи зарегистрировались, поэтому я ограничиваю количество вызовов во временном окне, если они не аутентифицированы. Для этого я создал специальный плагин Apache APISIX. После того, как количество вызовов достигло предела, он возвращает:

HTTP/1.1 429 Too Many Requests
Date: Fri, 28 Oct 2022 11:56:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.15.0

{"error_msg":"Please register at https:\/\/apisix.org\/register to get your API token and enjoy unlimited calls"}
Войти в полноэкранный режим

Выйти из полноэкранного режима

Давайте структурируем сообщение в соответствии с RFC 7807.

Детали проблемы JSON для регистрации


Вывод

RFC 7807 помогает не только разработчикам клиентов. Это огромная помощь разработчикам API, поскольку в нем содержатся краткие рекомендации, позволяющие не изобретать велосипед в каждом проекте.

Идти дальше:

Первоначально опубликовано на Java-компьютерщик 30 октябряй2022 г.