Webhooks de OpenAPI¶
Hay casos donde quieres decirle a los usuarios de tu API que tu aplicaci贸n podr铆a llamar a su aplicaci贸n (enviando una request) con algunos datos, normalmente para notificar de alg煤n tipo de evento.
Esto significa que en lugar del proceso normal de tus usuarios enviando requests a tu API, es tu API (o tu aplicaci贸n) la que podr铆a enviar requests a su sistema (a su API, su aplicaci贸n).
Esto normalmente se llama un webhook.
Pasos de los webhooks¶
El proceso normalmente es que t煤 defines en tu c贸digo cu谩l es el mensaje que enviar谩s, el body de la request.
Tambi茅n defines de alguna manera en qu茅 momentos tu aplicaci贸n enviar谩 esas requests o eventos.
Y tus usuarios definen de alguna manera (por ejemplo en un panel web en alg煤n lugar) el URL donde tu aplicaci贸n deber铆a enviar esas requests.
Toda la l贸gica sobre c贸mo registrar los URLs para webhooks y el c贸digo para realmente enviar esas requests depende de ti. Lo escribes como quieras en tu propio c贸digo.
Documentando webhooks con FastAPI y OpenAPI¶
Con FastAPI, usando OpenAPI, puedes definir los nombres de estos webhooks, los tipos de operaciones HTTP que tu aplicaci贸n puede enviar (por ejemplo, POST, PUT, etc.) y los bodies de las requests que tu aplicaci贸n enviar铆a.
Esto puede hacer mucho m谩s f谩cil para tus usuarios implementar sus APIs para recibir tus requests de webhook, incluso podr铆an ser capaces de autogenerar algo de su propio c贸digo de API.
Informaci贸n
Los webhooks est谩n disponibles en OpenAPI 3.1.0 y superiores, soportados por FastAPI 0.99.0 y superiores.
Una aplicaci贸n con webhooks¶
Cuando creas una aplicaci贸n de FastAPI, hay un atributo webhooks que puedes usar para definir webhooks, de la misma manera que definir铆as path operations, por ejemplo con @app.webhooks.post().
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"]
Los webhooks que defines terminar谩n en el esquema de OpenAPI y en la interfaz autom谩tica de documentaci贸n.
Informaci贸n
El objeto app.webhooks es en realidad solo un APIRouter, el mismo tipo que usar铆as al estructurar tu aplicaci贸n con m煤ltiples archivos.
Nota que con los webhooks en realidad no est谩s declarando un path (como /items/), el texto que pasas all铆 es solo un identificador del webhook (el nombre del evento), por ejemplo en @app.webhooks.post("new-subscription"), el nombre del webhook es new-subscription.
Esto es porque se espera que tus usuarios definan el actual URL path donde quieren recibir la request del webhook de alguna otra manera (por ejemplo, un panel web).
Revisa la documentaci贸n¶
Ahora puedes iniciar tu app e ir a http://127.0.0.1:8000/docs.
Ver谩s que tu documentaci贸n tiene las path operations normales y ahora tambi茅n algunos webhooks:
