OpenAPI Webhook'lar

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

Bazı durumlarda, API'nizi kullanan kullanıcılara uygulamanızın onların uygulamasını (request göndererek) bazı verilerle çağırabileceğini; genellikle bir tür event hakkında bildirim yapmak için kullanacağını söylemek istersiniz.

Bu da şunu ifade eder: Kullanıcılarınızın API'nize request göndermesi şeklindeki normal akış yerine, request'i sizin API'niz (veya uygulamanız) onların sistemine (onların API'sine, onların uygulamasına) gönderebilir.

Buna genellikle webhook denir.

Webhook adımları

Süreç genellikle şöyledir: Kodunuzda göndereceğiniz mesajın ne olduğunu, yani request'in body'sini siz tanımlarsınız.

Ayrıca uygulamanızın bu request'leri veya event'leri hangi anlarda göndereceğini de bir şekilde tanımlarsınız.

Ve kullanıcılarınız da bir şekilde (örneğin bir web dashboard üzerinden) uygulamanızın bu request'leri göndermesi gereken URL'yi tanımlar.

Webhook'lar için URL'lerin nasıl kaydedileceğine dair tüm mantık ve bu request'leri gerçekten gönderen kod tamamen size bağlıdır. Bunu kendi kodunuzda istediğiniz gibi yazarsınız.

FastAPI ve OpenAPI ile webhook'ları dokümante etmek

FastAPI ile OpenAPI kullanarak bu webhook'ların adlarını, uygulamanızın gönderebileceği HTTP operation türlerini (örn. POST, PUT, vb.) ve uygulamanızın göndereceği request body'lerini tanımlayabilirsiniz.

Bu, kullanıcılarınızın webhook request'lerinizi alacak şekilde API'lerini implement etmesini çok daha kolaylaştırabilir; hatta kendi API kodlarının bir kısmını otomatik üretebilirler.

Bilgi

Webhook'lar OpenAPI 3.1.0 ve üzeri sürümlerde mevcuttur; FastAPI 0.99.0 ve üzeri tarafından desteklenir.

Webhook'ları olan bir uygulama

Bir FastAPI uygulaması oluşturduğunuzda, webhook'ları tanımlamak için kullanabileceğiniz bir webhooks attribute'u vardır; path operation tanımlar gibi, örneğin @app.webhooks.post() ile.

Python 3.9+

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"]

Tanımladığınız webhook'lar OpenAPI şemasında ve otomatik docs UI'da yer alır.

Bilgi

app.webhooks nesnesi aslında sadece bir APIRouter'dır; uygulamanızı birden fazla dosya ile yapılandırırken kullanacağınız türün aynısıdır.

Dikkat edin: Webhook'larda aslında bir path (ör. /items/) deklare etmiyorsunuz; oraya verdiğiniz metin sadece webhook'un bir identifier'ıdır (event'in adı). Örneğin @app.webhooks.post("new-subscription") içinde webhook adı new-subscription'dır.

Bunun nedeni, webhook request'ini almak istedikleri gerçek URL path'i kullanıcılarınızın başka bir şekilde (örn. bir web dashboard üzerinden) tanımlamasının beklenmesidir.

Dokümanları kontrol edin

Şimdi uygulamanızı başlatıp http://127.0.0.1:8000/docs adresine gidin.

Dokümanlarınızda normal path operation'ları ve artık bazı webhook'ları da göreceksiniz: