Ana içeriğe geç

Request Body

🌐 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

Bir client'ten (örneğin bir tarayıcıdan) API'nize veri göndermeniz gerektiğinde, bunu request body olarak gönderirsiniz.

Bir request body, client'in API'nize gönderdiği veridir. Bir response body ise API'nizin client'e gönderdiği veridir.

API'niz neredeyse her zaman bir response body göndermek zorundadır. Ancak client'lerin her zaman request body göndermesi gerekmez; bazen sadece bir path isterler, belki birkaç query parametresiyle birlikte, ama body göndermezler.

Bir request body tanımlamak için, tüm gücü ve avantajlarıyla Pydantic modellerini kullanırsınız.

Bilgi

Veri göndermek için şunlardan birini kullanmalısınız: POST (en yaygını), PUT, DELETE veya PATCH.

GET request'i ile body göndermek, spesifikasyonlarda tanımsız bir davranıştır; yine de FastAPI bunu yalnızca çok karmaşık/uç kullanım senaryoları için destekler.

Önerilmediği için Swagger UI ile etkileşimli dokümanlar, GET kullanırken body için dokümantasyonu göstermez ve aradaki proxy'ler bunu desteklemeyebilir.

Pydantic'in BaseModel'ini import edin

Önce, pydantic içinden BaseModel'i import etmeniz gerekir:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Veri modelinizi oluşturun

Sonra veri modelinizi, BaseModel'den kalıtım alan bir class olarak tanımlarsınız.

Tüm attribute'lar için standart Python type'larını kullanın:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Query parametrelerini tanımlarken olduğu gibi, bir model attribute'ü default bir değere sahipse zorunlu değildir. Aksi halde zorunludur. Sadece opsiyonel yapmak için None kullanın.

Örneğin, yukarıdaki model şu şekilde bir JSON "object" (veya Python dict) tanımlar:

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

...description ve tax opsiyonel olduğu için (default değerleri None), şu JSON "object" da geçerli olur:

{
    "name": "Foo",
    "price": 45.2
}

Parametre olarak tanımlayın

Bunu path operation'ınıza eklemek için, path ve query parametrelerini tanımladığınız şekilde tanımlayın:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

...ve type'ını, oluşturduğunuz model olan Item olarak belirtin.

Sonuçlar

Sadece bu Python type tanımıyla, FastAPI şunları yapar:

  • Request'in body'sini JSON olarak okur.
  • İlgili type'lara dönüştürür (gerekirse).
  • Veriyi doğrular (validate eder).
    • Veri geçersizse, tam olarak nerede ve hangi verinin hatalı olduğunu söyleyen, anlaşılır bir hata döndürür.
  • Aldığı veriyi item parametresi içinde size verir.
    • Fonksiyonda bunun type'ını Item olarak tanımladığınız için, tüm attribute'lar ve type'ları için editor desteğini (tamamlama vb.) de alırsınız.
  • Modeliniz için JSON Schema tanımları üretir; projeniz için anlamlıysa bunları başka yerlerde de kullanabilirsiniz.
  • Bu şemalar üretilen OpenAPI şemasının bir parçası olur ve otomatik dokümantasyon UIs tarafından kullanılır.

Otomatik dokümanlar

Modellerinizin JSON Schema'ları, OpenAPI tarafından üretilen şemanın bir parçası olur ve etkileşimli API dokümanlarında gösterilir:

Ayrıca, ihtiyaç duyan her path operation içindeki API dokümanlarında da kullanılır:

Editor desteği

Editor'ünüzde, fonksiyonunuzun içinde her yerde type hint'leri ve tamamlama (completion) alırsınız (Pydantic modeli yerine dict alsaydınız bu olmazdı):

Yanlış type işlemleri için hata kontrolleri de alırsınız:

Bu bir tesadüf değil; tüm framework bu tasarımın etrafında inşa edildi.

Ayrıca, bunun tüm editor'lerle çalışacağından emin olmak için herhangi bir implementasyon yapılmadan önce tasarım aşamasında kapsamlı şekilde test edildi.

Hatta bunu desteklemek için Pydantic'in kendisinde bile bazı değişiklikler yapıldı.

Önceki ekran görüntüleri Visual Studio Code ile alınmıştır.

Ancak PyCharm ve diğer Python editor'lerinin çoğunda da aynı editor desteğini alırsınız:

İpucu

Editor olarak PyCharm kullanıyorsanız, Pydantic PyCharm Plugin kullanabilirsiniz.

Pydantic modelleri için editor desteğini şu açılardan iyileştirir:

  • auto-completion
  • type checks
  • refactoring
  • searching
  • inspections

Modeli kullanın

Fonksiyonun içinde model nesnesinin tüm attribute'larına doğrudan erişebilirsiniz:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax is not None:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax is not None:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

Request body + path parametreleri

Path parametrelerini ve request body'yi aynı anda tanımlayabilirsiniz.

FastAPI, path parametreleriyle eşleşen fonksiyon parametrelerinin path'ten alınması gerektiğini ve Pydantic model olarak tanımlanan fonksiyon parametrelerinin request body'den alınması gerektiğini anlayacaktır.

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.model_dump()}
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.model_dump()}

Request body + path + query parametreleri

body, path ve query parametrelerini aynı anda da tanımlayabilirsiniz.

FastAPI bunların her birini tanır ve veriyi doğru yerden alır.

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result
🤓 Other versions and variants 
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: Union[str, None] = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

Fonksiyon parametreleri şu şekilde tanınır:

  • Parametre, path içinde de tanımlıysa path parametresi olarak kullanılır.
  • Parametre tekil bir type'taysa (int, float, str, bool vb.), query parametresi olarak yorumlanır.
  • Parametre bir Pydantic model type'ı olarak tanımlandıysa, request body olarak yorumlanır.

Not

FastAPI, q değerinin zorunlu olmadığını = None default değerinden anlayacaktır.

str | None (Python 3.10+) veya Union[str, None] (Python 3.9+) içindeki Union, FastAPI tarafından bu değerin zorunlu olmadığını belirlemek için kullanılmaz; FastAPI bunun zorunlu olmadığını = None default değeri olduğu için bilir.

Ancak type annotation'larını eklemek, editor'ünüzün size daha iyi destek vermesini ve hataları yakalamasını sağlar.

Pydantic olmadan

Pydantic modellerini kullanmak istemiyorsanız, Body parametrelerini de kullanabilirsiniz. Body - Multiple Parameters: Singular values in body dokümanına bakın.