Вебхуки OpenAPI

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

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

Обычно это называется вебхуком.

Шаги вебхуков

Обычно процесс таков: вы определяете в своем коде, какое сообщение вы будете отправлять, то есть тело запроса.

Вы также определяете, в какие моменты (при каких событиях) ваше приложение будет отправлять эти запросы.

А ваши пользователи каким-то образом (например, в веб‑панели) указывают URL-адрес, на который ваше приложение должно отправлять эти запросы.

Вся логика регистрации URL-адресов для вебхуков и код, который реально отправляет эти запросы, целиком на вашей стороне. Вы пишете это так, как вам нужно, в своем собственном коде.

Документирование вебхуков с помощью FastAPI и OpenAPI

С FastAPI, используя OpenAPI, вы можете определить имена этих вебхуков, типы HTTP-операций, которые ваше приложение может отправлять (например, POST, PUT и т.д.), а также тела запросов, которые ваше приложение будет отправлять.

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

Информация

Вебхуки доступны в OpenAPI 3.1.0 и выше, поддерживаются в FastAPI 0.99.0 и новее.

Приложение с вебхуками

При создании приложения на FastAPI есть атрибут webhooks, с помощью которого можно объявлять вебхуки так же, как вы объявляете операции пути (обработчики пути), например с @app.webhooks.post().

Python 3.8+

from datetime import datetime

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Subscription(BaseModel):
    username: str
    monthly_fee: float
    start_date: datetime


@app.webhooks.post("new-subscription")
def new_subscription(body: Subscription):
    """
    When a new user subscribes to your service we'll send you a POST request with this
    data to the URL that you register for the event `new-subscription` in the dashboard.
    """


@app.get("/users/")
def read_users():
    return ["Rick", "Morty"]

Определенные вами вебхуки попадут в схему OpenAPI и в автоматический интерфейс документации.

Информация

Объект app.webhooks на самом деле — это обычный APIRouter, тот же тип, который вы используете при структурировании приложения по нескольким файлам.

Обратите внимание: в случае с вебхуками вы на самом деле не объявляете путь (например, /items/), передаваемый туда текст — это лишь идентификатор вебхука (имя события). Например, в @app.webhooks.post("new-subscription") имя вебхука — new-subscription.

Это связано с тем, что предполагается: фактический URL‑путь, по которому они хотят получать запрос вебхука, ваши пользователи укажут каким-то другим образом (например, в веб‑панели).

Посмотрите документацию

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

Вы увидите, что в документации есть обычные операции пути, а также появились вебхуки: