Response Model - Dönüş Tipi¶

Path operation functiondönüş tipini (return type) type annotation ile belirtip response için kullanılacak tipi tanımlayabilirsiniz.

Fonksiyonparametreleri için input data’da kullandığınıztype annotations yaklaşımının aynısını burada da kullanabilirsiniz; Pydantic model’leri, list’ler, dict’ler, integer, boolean gibi skaler değerler vb.

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:list[str]=[]@app.post("/items/")asyncdefcreate_item(item:Item)->Item:returnitem@app.get("/items/")asyncdefread_items()->list[Item]:return[Item(name="Portal Gun",price=42.0),Item(name="Plumbus",price=32.0),]

FastAPI bu dönüş tipini şunlar için kullanır:

• Dönen veriyidoğrulamak (validate).
  • Veri geçersizse (ör. bir field eksikse), busizin uygulama kodunuzun bozuk olduğu, olması gerekeni döndürmediği anlamına gelir; bu yüzden yanlış veri döndürmek yerine server error döner. Böylece siz ve client’larınız, beklenen veri ve veri şeklinin geleceğinden emin olabilirsiniz.
• OpenAPI’dekipath operation içine response için birJSON Schema eklemek.
  • Bu,otomatik dokümantasyon tarafından kullanılır.
  • Ayrıca otomatik client code generation araçları tarafından da kullanılır.

Ama en önemlisi:

• Çıktı verisini, dönüş tipinde tanımlı olana göresınırlar ve filtreler.
  • Bu, özelliklegüvenlik açısından önemlidir; aşağıda daha fazlasını göreceğiz.

response_model Parametresi¶

Bazı durumlarda, tam olarak dönüş tipinin söylediği gibi olmayan bir veriyi döndürmeniz gerekebilir ya da isteyebilirsiniz.

Örneğin,bir dict veya bir veritabanı objesi döndürmek isteyip, amaonu bir Pydantic model olarak declare etmek isteyebilirsiniz. Böylece Pydantic model, döndürdüğünüz obje (ör. dict veya veritabanı objesi) için dokümantasyon, doğrulama vb. işlerin tamamını yapar.

Eğer dönüş tipi annotation’ını eklerseniz, araçlar ve editörler (doğru şekilde) fonksiyonunuzun, declare ettiğiniz tipten (ör. Pydantic model) farklı bir tip (ör. dict) döndürdüğünü söyleyip hata verir.

Bu gibi durumlarda, dönüş tipi yerinepath operation decorator parametresi olanresponse_model’i kullanabilirsiniz.

response_model parametresini herhangi birpath operation içinde kullanabilirsiniz:

• @app.get()
• @app.post()
• @app.put()
• @app.delete()
• vb.

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:list[str]=[]@app.post("/items/",response_model=Item)asyncdefcreate_item(item:Item)->Any:returnitem@app.get("/items/",response_model=list[Item])asyncdefread_items()->Any:return[{"name":"Portal Gun","price":42.0},{"name":"Plumbus","price":32.0},]

response_model, Pydantic model field’ı için declare edeceğiniz aynı tipi alır; yani bir Pydantic model olabilir ama örneğinList[Item] gibi Pydantic model’lerden oluşan birlist de olabilir.

FastAPI buresponse_model’i; dokümantasyon, doğrulama vb. her şey için ve ayrıca çıktı verisinitip tanımına göre dönüştürmek ve filtrelemek için kullanır.

response_model Önceliği¶

Hem dönüş tipi hem deresponse_model declare ederseniz, FastAPI’deresponse_model önceliklidir ve o kullanılır.

Böylece, response model’den farklı bir tip döndürdüğünüz durumlarda bile editör ve mypy gibi araçlar için fonksiyonlarınıza doğru type annotation’lar ekleyebilir, aynı zamanda FastAPI’ninresponse_model üzerinden veri doğrulama, dokümantasyon vb. yapmasını sağlayabilirsiniz.

Ayrıcaresponse_model=None kullanarak, ilgilipath operation için response model oluşturulmasını devre dışı bırakabilirsiniz. Bu, Pydantic field’ı olarak geçerli olmayan şeyler için type annotation eklediğinizde gerekebilir; aşağıdaki bölümlerden birinde bunun örneğini göreceksiniz.

Aynı input verisini geri döndürmek¶

BuradaUserIn adında bir model declare ediyoruz; bu model plaintext bir password içerecek:

fromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=None# Don't do this in production!@app.post("/user/")asyncdefcreate_user(user:UserIn)->UserIn:returnuser

$pipinstallemail-validator

$pipinstall"pydantic[email]"

Bu model ile hem input’u declare ediyoruz hem de output’u aynı model ile declare ediyoruz:

fromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=None# Don't do this in production!@app.post("/user/")asyncdefcreate_user(user:UserIn)->UserIn:returnuser

Artık bir browser password ile user oluşturduğunda, API response içinde aynı password’ü geri döndürecek.

Bu örnekte sorun olmayabilir; çünkü password’ü gönderen kullanıcı zaten aynı kişi.

Namun ancak aynı modeli başka birpath operation için kullanırsak, kullanıcının password’lerini her client’a gönderiyor olabiliriz.

Bir output modeli ekleyin¶

Bunun yerine, plaintext password içeren bir input modeli ve password’ü içermeyen bir output modeli oluşturabiliriz:

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=NoneclassUserOut(BaseModel):username:stremail:EmailStrfull_name:str|None=None@app.post("/user/",response_model=UserOut)asyncdefcreate_user(user:UserIn)->Any:returnuser

Buradapath operation function password içeren aynı input user’ı döndürüyor olsa bile:

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=NoneclassUserOut(BaseModel):username:stremail:EmailStrfull_name:str|None=None@app.post("/user/",response_model=UserOut)asyncdefcreate_user(user:UserIn)->Any:returnuser

...response_model olarak, password’ü içermeyenUserOut modelimizi declare ettik:

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=NoneclassUserOut(BaseModel):username:stremail:EmailStrfull_name:str|None=None@app.post("/user/",response_model=UserOut)asyncdefcreate_user(user:UserIn)->Any:returnuser

DolayısıylaFastAPI, output model’de declare edilmemiş tüm verileri (Pydantic kullanarak) filtrelemekle ilgilenir.

response_model mi Return Type mı?¶

Bu durumda iki model farklı olduğu için fonksiyon dönüş tipiniUserOut olarak annotate etseydik, editör ve araçlar farklı class’lar olduğu için geçersiz bir tip döndürdüğümüzü söyleyip hata verecekti.

Bu yüzden bu örnekteresponse_model parametresinde declare etmek zorundayız.

...ama bunu nasıl aşabileceğinizi görmek için aşağıyı okumaya devam edin.

Return Type ve Veri Filtreleme¶

Önceki örnekten devam edelim. Fonksiyonutek bir tip ile annotate etmek istiyoruz; ama fonksiyondan gerçektedaha fazla veri içeren bir şey döndürebilmek istiyoruz.

FastAPI’nin response model’i kullanarak veriyifiltrelemeye devam etmesini istiyoruz. Yani fonksiyon daha fazla veri döndürse bile response, sadece response model’de declare edilmiş field’ları içersin.

Önceki örnekte class’lar farklı olduğu içinresponse_model parametresini kullanmak zorundaydık. Ancak bu, editör ve araçların fonksiyon dönüş tipi kontrolünden gelen desteğini alamadığımız anlamına da geliyor.

Ama bu tarz durumların çoğunda modelin amacı, bu örnekteki gibi bazı verilerifiltrelemek/kaldırmak olur.

Bu gibi durumlarda class’lar ve inheritance kullanarak, fonksiyontype annotations sayesinde editör ve araçlarda daha iyi destek alabilir, aynı zamanda FastAPI’ninveri filtrelemesini de koruyabiliriz.

fromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classBaseUser(BaseModel):username:stremail:EmailStrfull_name:str|None=NoneclassUserIn(BaseUser):password:str@app.post("/user/")asyncdefcreate_user(user:UserIn)->BaseUser:returnuser

Bununla birlikte, code type’lar açısından doğru olduğu için editörler ve mypy araç desteği verir; ayrıca FastAPI’den veri filtrelemeyi de alırız.

Bu nasıl çalışıyor? Bir bakalım. 🤓

Type Annotations ve Araç Desteği¶

Önce editörler, mypy ve diğer araçlar bunu nasıl görür, ona bakalım.

BaseUser temel field’lara sahiptir. ArdındanUserIn,BaseUser’dan miras alır vepassword field’ını ekler; yani iki modelin field’larının tamamını içerir.

Fonksiyonun dönüş tipiniBaseUser olarak annotate ediyoruz ama gerçekte birUserIn instance’ı döndürüyoruz.

Editör, mypy ve diğer araçlar buna itiraz etmez; çünkü typing açısındanUserIn,BaseUser’ın subclass’ıdır. Bu da, birBaseUser bekleniyorkenUserIn’ingeçerli bir tip olduğu anlamına gelir.

FastAPI Veri Filtreleme¶

FastAPI açısından ise dönüş tipini görür ve döndürdüğünüz şeyinyalnızca tipte declare edilen field’ları içerdiğinden emin olur.

FastAPI, Pydantic ile içeride birkaç işlem yapar; böylece class inheritance kurallarının dönen veri filtrelemede aynen kullanılmasına izin vermez. Aksi halde beklediğinizden çok daha fazla veriyi response’ta döndürebilirdiniz.

Bu sayede iki dünyanın da en iyisini alırsınız:araç desteği veren type annotations veveri filtreleme.

Dokümanlarda görün¶

Otomatik dokümanları gördüğünüzde, input model ve output model’in her birinin kendi JSON Schema’sına sahip olduğunu kontrol edebilirsiniz:

Ve her iki model de etkileşimli API dokümantasyonunda kullanılır:

Diğer Return Type Annotation’ları¶

Bazı durumlarda Pydantic field olarak geçerli olmayan bir şey döndürebilir ve bunu fonksiyonda annotate edebilirsiniz; amaç sadece araçların (editör, mypy vb.) sağladığı desteği almaktır.

Doğrudan Response Döndürmek¶

En yaygın durum,ileri seviye dokümanlarda daha sonra anlatıldığı gibi doğrudan bir Response döndürmektir.

fromfastapiimportFastAPI,Responsefromfastapi.responsesimportJSONResponse,RedirectResponseapp=FastAPI()@app.get("/portal")asyncdefget_portal(teleport:bool=False)->Response:ifteleport:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")returnJSONResponse(content={"message":"Here's your interdimensional portal."})

Bu basit durum FastAPI tarafından otomatik olarak ele alınır; çünkü dönüş tipi annotation’ıResponse class’ıdır (veya onun bir subclass’ı).

Araçlar da memnun olur; çünkü hemRedirectResponse hemJSONResponse,Response’un subclass’ıdır. Yani type annotation doğrudur.

Bir Response Subclass’ını Annotate Etmek¶

Type annotation içindeResponse’un bir subclass’ını da kullanabilirsiniz:

fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/teleport")asyncdefget_teleport()->RedirectResponse:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")

Bu da çalışır; çünküRedirectResponse,Response’un subclass’ıdır ve FastAPI bu basit durumu otomatik olarak yönetir.

Geçersiz Return Type Annotation’ları¶

Ancak geçerli bir Pydantic tipi olmayan başka rastgele bir obje (ör. bir veritabanı objesi) döndürür ve fonksiyonu da öyle annotate ederseniz, FastAPI bu type annotation’dan bir Pydantic response model oluşturmaya çalışır ve başarısız olur.

Aynı şey, farklı tipler arasında birbirleşim kullandığınızda ve bu tiplerden biri veya birkaçı geçerli bir Pydantic tipi değilse de olur; örneğin şu kullanım patlar 💥:

fromfastapiimportFastAPI,Responsefromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/portal")asyncdefget_portal(teleport:bool=False)->Response|dict:ifteleport:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")return{"message":"Here's your interdimensional portal."}

...bu, type annotation Pydantic tipi olmadığı ve tek birResponse class’ı (veya subclass’ı) olmadığı için başarısız olur; bu, birResponse ile birdict arasında union’dır (ikiden herhangi biri).

Response Model’i Devre Dışı Bırakmak¶

Yukarıdaki örnekten devam edersek; FastAPI’nin varsayılan olarak yaptığı veri doğrulama, dokümantasyon, filtreleme vb. işlemleri istemiyor olabilirsiniz.

Ancak yine de editörler ve type checker’lar (ör. mypy) gibi araçların desteğini almak için fonksiyonda dönüş tipi annotation’ını korumak isteyebilirsiniz.

Bu durumdaresponse_model=None ayarlayarak response model üretimini devre dışı bırakabilirsiniz:

fromfastapiimportFastAPI,Responsefromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/portal",response_model=None)asyncdefget_portal(teleport:bool=False)->Response|dict:ifteleport:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")return{"message":"Here's your interdimensional portal."}

Bu, FastAPI’nin response model üretimini atlamasını sağlar; böylece FastAPI uygulamanızı etkilemeden ihtiyacınız olan herhangi bir return type annotation’ını kullanabilirsiniz. 🤓

Response Model encoding parametreleri¶

Response model’inizde şu şekilde default değerler olabilir:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5tags:list[str]=[]items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The bartenders","price":62,"tax":20.2},"baz":{"name":"Baz","description":None,"price":50.2,"tax":10.5,"tags":[]},}@app.get("/items/{item_id}",response_model=Item,response_model_exclude_unset=True)asyncdefread_item(item_id:str):returnitems[item_id]

• description: Union[str, None] = None (veya Python 3.10’dastr | None = None) için defaultNone’dır.
• tax: float = 10.5 için default10.5’tir.
• tags: List[str] = [] için default, boş bir list’tir:[].

Ancak gerçekte kaydedilmedilerse, bunları sonuçtan çıkarmak isteyebilirsiniz.

Örneğin NoSQL veritabanında çok sayıda optional attribute içeren modelleriniz varsa, default değerlerle dolu çok uzun JSON response’ları göndermek istemeyebilirsiniz.

response_model_exclude_unset parametresini kullanın¶

Path operation decorator parametresi olarakresponse_model_exclude_unset=True ayarlayabilirsiniz:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5tags:list[str]=[]items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The bartenders","price":62,"tax":20.2},"baz":{"name":"Baz","description":None,"price":50.2,"tax":10.5,"tags":[]},}@app.get("/items/{item_id}",response_model=Item,response_model_exclude_unset=True)asyncdefread_item(item_id:str):returnitems[item_id]

böylece response’a default değerler dahil edilmez; yalnızca gerçekten set edilmiş değerler gelir.

Dolayısıyla ID’sifoo olan item için bupath operation’a request atarsanız, response (default değerler olmadan) şöyle olur:

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

Default’u olan field’lar için değer içeren data¶

Ama data’nız modelde default değeri olan field’lar için değer içeriyorsa, örneğin ID’sibar olan item gibi:

{"name":"Bar","description":"The bartenders","price":62,"tax":20.2}

bunlar response’a dahil edilir.

Default değerlerle aynı değerlere sahip data¶

Eğer data, default değerlerle aynı değerlere sahipse, örneğin ID’sibaz olan item gibi:

{"name":"Baz","description":None,"price":50.2,"tax":10.5,"tags":[]}

FastAPI yeterince akıllıdır (aslında Pydantic yeterince akıllıdır) vedescription,tax,tags default ile aynı olsa bile bunların explicit olarak set edildiğini (default’tan alınmadığını) anlar.

Bu yüzden JSON response içinde yer alırlar.

response_model_include veresponse_model_exclude¶

Ayrıcapath operation decorator parametreleriresponse_model_include veresponse_model_exclude’u da kullanabilirsiniz.

Bunlar; dahil edilecek attribute isimlerini (geri kalanını atlayarak) ya da hariç tutulacak attribute isimlerini (geri kalanını dahil ederek) belirtenstr değerlerinden oluşan birset alır.

Tek bir Pydantic model’iniz varsa ve output’tan bazı verileri hızlıca çıkarmak istiyorsanız, bu yöntem pratik bir kısayol olabilir.

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The Bar fighters","price":62,"tax":20.2},"baz":{"name":"Baz","description":"There goes my baz","price":50.2,"tax":10.5,},}@app.get("/items/{item_id}/name",response_model=Item,response_model_include={"name","description"},)asyncdefread_item_name(item_id:str):returnitems[item_id]@app.get("/items/{item_id}/public",response_model=Item,response_model_exclude={"tax"})asyncdefread_item_public_data(item_id:str):returnitems[item_id]

set yerinelist kullanmak¶

Yanlışlıklaset yerinelist veyatuple kullanırsanız, FastAPI bunu yineset’e çevirir ve doğru şekilde çalışır:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The Bar fighters","price":62,"tax":20.2},"baz":{"name":"Baz","description":"There goes my baz","price":50.2,"tax":10.5,},}@app.get("/items/{item_id}/name",response_model=Item,response_model_include=["name","description"],)asyncdefread_item_name(item_id:str):returnitems[item_id]@app.get("/items/{item_id}/public",response_model=Item,response_model_exclude=["tax"])asyncdefread_item_public_data(item_id:str):returnitems[item_id]

Özet¶

Response model’leri tanımlamak ve özellikle private data’nın filtrelendiğinden emin olmak içinpath operation decorator parametresiresponse_model’i kullanın.

Yalnızca explicit olarak set edilmiş değerleri döndürmek içinresponse_model_exclude_unset kullanın.