fastapi/docs/tr/docs/tutorial/path-params.md

Yol Parametreleri

Python string biçimlemede kullanılan sözdizimiyle path "parametreleri"ni veya "değişkenleri"ni tanımlayabilirsiniz:

{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}

Path parametresi item_id'nin değeri, fonksiyonunuza item_id argümanı olarak aktarılacaktır.

Yani, bu örneği çalıştırıp http://127.0.0.1:8000/items/foo adresine giderseniz, şöyle bir response görürsünüz:

{"item_id":"foo"}

Tip İçeren Yol Parametreleri

Standart Python tip belirteçlerini kullanarak path parametresinin tipini fonksiyonun içinde tanımlayabilirsiniz:

{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *}

Bu durumda, item_id bir int olarak tanımlanır.

/// check | Ek bilgi

Bu sayede, fonksiyon içinde hata denetimi, kod tamamlama vb. konularda editör desteğine kavuşursunuz.

///

Veri conversion

Bu örneği çalıştırıp tarayıcınızda http://127.0.0.1:8000/items/3 adresini açarsanız, şöyle bir response görürsünüz:

{"item_id":3}

/// check | Ek bilgi

Dikkat edin: fonksiyonunuzun aldığı (ve döndürdüğü) değer olan 3, string "3" değil, bir Python int'idir.

Yani, bu tip tanımıyla birlikte FastAPI size otomatik request "parsing" sağlar.

///

Veri Doğrulama

Ancak tarayıcınızda http://127.0.0.1:8000/items/foo adresine giderseniz, şuna benzer güzel bir HTTP hatası görürsünüz:

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": [
        "path",
        "item_id"
      ],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

çünkü path parametresi item_id, int olmayan "foo" değerine sahipti.

Aynı hata, şu örnekte olduğu gibi int yerine float verirseniz de ortaya çıkar: http://127.0.0.1:8000/items/4.2

/// check | Ek bilgi

Yani, aynı Python tip tanımıyla birlikte FastAPI size veri doğrulama sağlar.

Dikkat edin: hata ayrıca doğrulamanın geçmediği noktayı da açıkça belirtir.

Bu, API'ınızla etkileşime giren kodu geliştirirken ve debug ederken inanılmaz derecede faydalıdır.

///

Dokümantasyon

Tarayıcınızı http://127.0.0.1:8000/docs adresinde açtığınızda, aşağıdaki gibi otomatik ve interaktif bir API dokümantasyonu görürsünüz:

/// check | Ek bilgi

Yine, sadece aynı Python tip tanımıyla FastAPI size otomatik ve interaktif dokümantasyon (Swagger UI entegrasyonuyla) sağlar.

Dikkat edin: path parametresi integer olarak tanımlanmıştır.

///

Standartlara Dayalı Avantajlar, Alternatif Dokümantasyon

Üretilen şema OpenAPI standardından geldiği için birçok uyumlu araç vardır.

Bu nedenle FastAPI'ın kendisi, http://127.0.0.1:8000/redoc adresinden erişebileceğiniz alternatif bir API dokümantasyonu (ReDoc kullanarak) sağlar:

Aynı şekilde, birçok uyumlu araç vardır. Birçok dil için kod üretme araçları da buna dahildir.

Pydantic

Tüm veri doğrulamaları, arka planda Pydantic tarafından gerçekleştirilir; böylece onun tüm avantajlarından faydalanırsınız. Ve emin ellerde olduğunuzu bilirsiniz.

Aynı tip tanımlarını str, float, bool ve daha birçok karmaşık veri tipiyle kullanabilirsiniz.

Bunların birkaçı, eğitimin sonraki bölümlerinde ele alınacaktır.

Sıralama Önemlidir

Path operation'lar oluştururken sabit bir path'e sahip olduğunuz durumlarla karşılaşabilirsiniz.

Örneğin /users/me'nin, geçerli kullanıcı hakkında veri almak için kullanıldığını varsayalım.

Sonra belirli bir kullanıcı hakkında, kullanıcı ID'si ile veri almak için /users/{user_id} şeklinde bir path'iniz de olabilir.

Path operation'lar sırayla değerlendirildiği için, /users/me için olan path'in /users/{user_id} olandan önce tanımlandığından emin olmanız gerekir:

{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *}

Aksi halde, /users/{user_id} için olan path, "me" değerini user_id parametresi olarak aldığını "düşünerek" /users/me için de eşleşir.

Benzer şekilde, bir path operation'ı yeniden tanımlayamazsınız:

{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}

Path önce eşleştiği için her zaman ilk olan kullanılır.

Ön Tanımlı Değerler

Bir path operation'ınız path parameter alıyorsa ama olası geçerli path parameter değerlerinin önceden tanımlı olmasını istiyorsanız, standart bir Python Enum kullanabilirsiniz.

Bir Enum Sınıfı Oluşturalım

Enum'u import edin ve str ile Enum'dan miras alan bir alt sınıf oluşturun.

str'den miras aldığınızda API dokümanları değerlerin string tipinde olması gerektiğini anlayabilir ve doğru şekilde render edebilir.

Sonra, kullanılabilir geçerli değerler olacak sabit değerli class attribute'ları oluşturun:

{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}

/// tip | İpucu

Merak ediyorsanız: "AlexNet", "ResNet" ve "LeNet", Makine Öğrenmesi modellerinin sadece isimleridir.

///

Bir Path Parameter Tanımlayalım

Ardından oluşturduğunuz enum sınıfını (ModelName) kullanarak tip belirteciyle bir path parameter oluşturun:

{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}

Dokümana Göz Atalım

Path parameter için kullanılabilir değerler ön tanımlı olduğu için, interaktif dokümanlar bunları güzelce gösterebilir:

Python Enumeration'ları ile Çalışmak

Path parameter'ın değeri bir enumeration member olacaktır.

Enumeration Member'ları Karşılaştıralım

Bunu, oluşturduğunuz enum ModelName içindeki enumeration member ile karşılaştırabilirsiniz:

{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}

Enumeration Value'yu Alalım

Gerçek değeri (bu durumda bir str) model_name.value ile veya genel olarak your_enum_member.value ile alabilirsiniz:

{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}

/// tip | İpucu

"lenet" değerine ModelName.lenet.value ile de erişebilirsiniz.

///

Enumeration Member'ları Döndürelim

Path operation'ınızdan, bir JSON body'nin içine gömülü olsalar bile (ör. bir dict) enum member'ları döndürebilirsiniz.

İstemciye dönmeden önce, karşılık gelen değerlerine (bu durumda string) dönüştürülürler:

{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *}

İstemcinizde şöyle bir JSON response alırsınız:

{
  "model_name": "alexnet",
  "message": "Deep Learning FTW!"
}

Path İçeren Path Parametreleri

Diyelim ki /files/{file_path} path'ine sahip bir path operation'ınız var.

Ama file_path'in kendisinin home/johndoe/myfile.txt gibi bir path içermesi gerekiyor.

Böylece, o dosyanın URL'si şu şekilde olur: /files/home/johndoe/myfile.txt.

OpenAPI Desteği

OpenAPI, içinde bir path barındıracak bir path parameter tanımlamak için bir yöntem desteklemez; çünkü bu, test etmesi ve tanımlaması zor senaryolara yol açabilir.

Yine de, Starlette'in dahili araçlarından birini kullanarak bunu FastAPI'da yapabilirsiniz.

Ve dokümanlar, parametrenin bir path içermesi gerektiğini söyleyen herhangi bir dokümantasyon eklemese bile çalışmaya devam eder.

Path Dönüştürücü

Starlette'ten doğrudan gelen bir seçenekle, path içeren bir path parameter'ı şu URL ile tanımlayabilirsiniz:

/files/{file_path:path}

Bu durumda parametrenin adı file_path'tir ve son kısım olan :path, parametrenin herhangi bir path ile eşleşmesi gerektiğini söyler.

Yani şununla kullanabilirsiniz:

{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *}

/// tip | İpucu

Parametrenin başında /home/johndoe/myfile.txt örneğinde olduğu gibi bir eğik çizgi (/) ile başlaması gerekebilir.

Bu durumda URL, files ile home arasında çift eğik çizgi (//) olacak şekilde /files//home/johndoe/myfile.txt olur.

///

Özet

FastAPI ile kısa, sezgisel ve standart Python tip tanımlarını kullanarak şunları elde edersiniz:

• Editör desteği: hata denetimleri, otomatik tamamlama vb.
• Veri "parsing"
• Veri doğrulama
• API annotation ve otomatik dokümantasyon

Ve bunları sadece bir kez tanımlamanız yeterlidir.

Bu, (ham performans dışında) FastAPI'ın alternatif framework'lere kıyasla muhtemelen en görünür ana avantajıdır.