OpenAPI Webhooks¶

ऐसे मामले होते हैं जहाँ आप अपने API users को बताना चाहते हैं कि आपकी app कुछ data के साथ (एक request भेजते हुए) उनकी app को कॉल कर सकती है, सामान्यतः किसी प्रकार के event की सूचना देने के लिए।

इसका मतलब है कि आपके users द्वारा आपकी API को requests भेजने की सामान्य प्रक्रिया के बजाय, आपकी API (या आपकी app) उनके system को requests भेज सकती है (उनकी API, उनकी app को)।

इसे सामान्यतः webhook कहा जाता है।

Webhooks के चरण¶

सामान्यतः प्रक्रिया यह होती है कि आप अपने code में define करते हैं कि आप कौन-सा message भेजेंगे, यानी request का body।

आप यह भी किसी तरीके से define करते हैं कि आपकी app किन क्षणों पर वे requests या events भेजेगी।

और आपके users किसी तरीके से (उदाहरण के लिए कहीं किसी web dashboard में) वह URL define करते हैं जहाँ आपकी app को वे requests भेजनी चाहिए।

Webhooks के लिए URLs को register करने की सारी logic और वास्तव में उन requests को भेजने का code आपके ऊपर है। आप इसे अपने खुद के code में जैसे चाहें वैसे लिखते हैं।

FastAPI और OpenAPI के साथ webhooks का दस्तावेज़ीकरण¶

FastAPI के साथ, OpenAPI का उपयोग करते हुए, आप इन webhooks के नाम, आपकी app द्वारा भेजे जा सकने वाले HTTP operations के प्रकार (जैसे POST, PUT, आदि) और आपकी app द्वारा भेजे जाने वाले request bodies define कर सकते हैं।

इससे आपके users के लिए आपकी webhook requests प्राप्त करने के लिए अपनी APIs implement करना बहुत आसान हो सकता है, वे शायद अपने कुछ API code को autogenerate भी कर सकें।

Webhooks वाली app¶

जब आप एक FastAPI application बनाते हैं, तो एक webhooks attribute होता है जिसका उपयोग आप webhooks define करने के लिए कर सकते हैं, उसी तरह जैसे आप path operations define करते हैं, उदाहरण के लिए @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"]

आप जिन webhooks को define करते हैं वे OpenAPI schema और automatic docs UI में आ जाएँगे।

ध्यान दें कि webhooks के साथ आप वास्तव में कोई path declare नहीं कर रहे हैं (जैसे /items/), वहाँ आप जो text pass करते हैं वह केवल webhook का एक identifier है (event का नाम), उदाहरण के लिए @app.webhooks.post("new-subscription") में, webhook का नाम new-subscription है।

ऐसा इसलिए है क्योंकि उम्मीद की जाती है कि आपके users उस वास्तविक URL path को किसी और तरीके से define करेंगे जहाँ वे webhook request प्राप्त करना चाहते हैं (जैसे कोई web dashboard)।

Docs देखें¶

अब आप अपनी app start कर सकते हैं और http://127.0.0.1:8000/docs पर जा सकते हैं।

आप देखेंगे कि आपके docs में सामान्य path operations हैं और अब कुछ webhooks भी हैं: