4.8 KiB

Raw Blame History

Вебхуки OpenAPI

Бувають випадки, коли ви хочете повідомити користувачів вашого API, що ваш застосунок може викликати їхній застосунок (надсилаючи запит) із деякими даними, зазвичай щоб сповістити про певний тип події.

Це означає, що замість звичного процесу, коли ваші користувачі надсилають запити до вашого 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_py310.py hl[9:12,15:20] *}

Визначені вами вебхуки потраплять до схеми OpenAPI та автоматичного інтерфейсу документації.

/// info | Інформація

Об'єкт app.webhooks насправді є просто APIRouter - тим самим типом, який ви використовуєте, структуризуючи застосунок у кількох файлах.

///

Зверніть увагу, що з вебхуками ви фактично не оголошуєте шлях (на кшталт /items/), текст, який ви передаєте там, - це лише ідентифікатор вебхука (назва події). Наприклад, у @app.webhooks.post("new-subscription") назва вебхука - new-subscription.

Це тому, що очікується, що ваші користувачі іншим способом (наприклад, у веб-дашборді) визначать фактичний URL-шлях, де вони хочуть отримувати запит вебхука.

Перевірте документацію

Тепер ви можете запустити свій застосунок і перейти за адресою http://127.0.0.1:8000/docs.

Ви побачите у своїй документації звичайні операції шляху, а також деякі вебхуки:

4.8 KiB Raw Blame History Unescape Escape