4.9 KiB
Вебхуки OpenAPI
Бывают случаи, когда вы хотите сообщить пользователям вашего API, что ваше приложение может вызвать их приложение (отправив HTTP-запрос) с некоторыми данными, обычно чтобы уведомить о каком-то событии.
Это означает, что вместо обычного процесса, когда пользователи отправляют запросы вашему API, ваш API (или ваше приложение) может отправлять запросы в их систему (в их API, их приложение).
Обычно это называется вебхуком.
Шаги вебхуков
Обычно процесс таков: вы определяете в своем коде, какое сообщение вы будете отправлять, то есть тело запроса.
Вы также определяете, в какие моменты (при каких событиях) ваше приложение будет отправлять эти запросы.
А ваши пользователи каким-то образом (например, в веб‑панели) указывают URL-адрес, на который ваше приложение должно отправлять эти запросы.
Вся логика регистрации URL-адресов для вебхуков и код, который реально отправляет эти запросы, целиком на вашей стороне. Вы пишете это так, как вам нужно, в своем собственном коде.
Документирование вебхуков с помощью FastAPI и OpenAPI
С FastAPI, используя OpenAPI, вы можете определить имена этих вебхуков, типы HTTP-операций, которые ваше приложение может отправлять (например, POST, PUT и т.д.), а также тела запросов, которые ваше приложение будет отправлять.
Это значительно упростит вашим пользователям реализацию их API для приема ваших вебхук-запросов; возможно, они даже смогут автоматически сгенерировать часть кода своего API.
/// info | Информация
Вебхуки доступны в OpenAPI 3.1.0 и выше, поддерживаются в FastAPI 0.99.0 и новее.
///
Приложение с вебхуками
При создании приложения на FastAPI есть атрибут webhooks, с помощью которого можно объявлять вебхуки так же, как вы объявляете операции пути (обработчики пути), например с @app.webhooks.post().
{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
Определенные вами вебхуки попадут в схему OpenAPI и в автоматический интерфейс документации.
/// info | Информация
Объект app.webhooks на самом деле — это обычный APIRouter, тот же тип, который вы используете при структурировании приложения по нескольким файлам.
///
Обратите внимание: в случае с вебхуками вы на самом деле не объявляете путь (например, /items/), передаваемый туда текст — это лишь идентификатор вебхука (имя события). Например, в @app.webhooks.post("new-subscription") имя вебхука — new-subscription.
Это связано с тем, что предполагается: фактический URL‑путь, по которому они хотят получать запрос вебхука, ваши пользователи укажут каким-то другим образом (например, в веб‑панели).
Посмотрите документацию
Теперь вы можете запустить приложение и перейти по ссылке http://127.0.0.1:8000/docs.
Вы увидите, что в документации есть обычные операции пути, а также появились вебхуки:
