FastAPI, Python ile API'ler oluşturmak için modern, yüksek performanslı bir web çerçevesidir. Öne çıkan özelliklerinden biri, geliştiricilerin esnek ve kullanıcı dostu API'ler oluşturmasına olanak tanıyan FastAPI sorgu parametrelerinin işlenmesidir. Bu makalede, 2024'te FastAPI sorgu parametrelerini etkili bir şekilde kullanmaya yönelik en iyi uygulamaları ve teknikleri inceleyeceğiz.
Neden FastAPI Sorgu Parametrelerini Kullanmalısınız?
- Esneklik: FastAPI sorgu parametreleri, istemcilerin isteklerinin sonuçlarını özelleştirmesine olanak tanır. Örneğin, kullanıcılar arama sonuçlarını kategori, fiyat veya derecelendirme gibi belirli kriterlere göre filtreleyebilir.
- Kullanılabilirlik: İstemciler ve API arasındaki etkileşimi basitleştirirler. İstemciler sorgu parametrelerini URL'ye kolayca ekleyebilirken, geliştiriciler bu parametreleri kodlarında hızla doğrulayabilir ve işleyebilir.
- Performans: FastAPI sorgu parametrelerini kullanarak, bir API için gereken uç nokta sayısını azaltabilirsiniz. Her filtreleme seçeneği için ayrı uç noktalar oluşturmak yerine, tek bir uç nokta birden fazla sorgu parametresini işleyebilir.
FastAPI Sorgu Parametreleri Nasıl Kullanılır
FastAPI Sorgu Parametrelerini Tanımlama
FastAPI'de sorgu parametrelerini tanımlamak için, bunları uç nokta tanımınızdaki işlev parametreleri olarak dahil etmeniz yeterlidir. İşte basit bir örnek:
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: str | None = Query(default=None, max_length=50),
skip: int = Query(default=0, ge=0),
limit: int = Query(default=10, le=100)
):
return {"q": q, "skip": skip, "limit": limit}Bu örnekte:
q: Maksimum 50 karakter uzunluğunda isteğe bağlı bir dize parametresi.skip: Varsayılan değeri 0 ve minimum değeri 0 olan, kaç öğenin atlanacağını belirten bir tamsayı parametresi.limit: Varsayılan değeri 10 ve maksimum değeri 100 olan, döndürülecek maksimum öğe sayısını belirten bir tamsayı parametresi.
FastAPI Sorgu Parametrelerine Erişim
Bir istemci uç noktaya bir istek yaptığında, FastAPI sorgu parametrelerini URL'den otomatik olarak çıkarır ve bunları işleve iletir. Örneğin, /items/?q=foo&skip=10&limit=5 adresine bir istek yapılırsa, işlev şunları alacaktır:
q = "foo"skip = 10limit = 5
Bu otomatik çıkarma, ek ayrıştırma mantığı olmadan FastAPI sorgu parametreleriyle çalışmayı kolaylaştırır.
İsteğe Bağlı ve Gerekli FastAPI Sorgu Parametreleri
Varsayılan olarak, FastAPI sorgu parametreleri isteğe bağlıdır. Bir parametre istekte sağlanmazsa, FastAPI belirtilen varsayılan değeri kullanacaktır. Bir sorgu parametresini gerekli yapmak için, varsayılan değeri atlamanız yeterlidir:
@app.get("/items/")
async def read_items(required_param: str):
return {"required_param": required_param}required_param isteğe dahil edilmezse, FastAPI gerekli bir sorgu parametresinin eksik olduğunu belirten 422 İşlenemeyen Varlık hatası döndürecektir.
FastAPI Sorgu Parametreleri için Birden Çok Değeri İşleme
FastAPI, birden çok değer kabul edebilen bir sorgu parametresi tanımlamanıza olanak tanır. Bunu, parametre türünü bir liste olarak belirterek yapabilirsiniz:
from typing import List
@app.get("/items/")
async def read_items(q: List[str] = Query(default=[])):
return {"q": q}Bu durumda, istemci /items/?q=foo&q=bar&q=baz gibi bir istek yapabilir ve FastAPI değerleri bir liste halinde ayrıştıracaktır. Bu özellik, kullanıcıların sonuçları birden çok kritere göre filtrelemek istediği senaryolar için özellikle kullanışlıdır.
FastAPI Sorgu Parametrelerini Doğrulama
FastAPI, Query işlevini kullanarak sorgu parametreleri için yerleşik doğrulama sağlar. Minimum ve maksimum değerler, uzunluk kısıtlamaları ve regex desenleri gibi kısıtlamalar belirtebilirsiniz. İşte bir örnek:
@app.get("/items/")
async def read_items(
q: str = Query(default=None, min_length=3, max_length=50),
item_id: int = Query(ge=1, le=100)
):
return {"q": q, "item_id": item_id}Bu örnekte, q minimum 3 ve maksimum 50 uzunluğunda bir dize olmalıdır. item_id 1 ile 100 arasında bir tamsayı olmalıdır. FastAPI bu kısıtlamaları otomatik olarak doğrulayacak ve giriş belirtilen kriterleri karşılamıyorsa bir hata döndürecektir.
FastAPI ve OpenAPI ile Otomatik Belge Oluşturma
FastAPI kullanmanın öne çıkan avantajlarından biri, etkileşimli API belgelerinin otomatik olarak oluşturulmasını sağlayan OpenAPI ile sorunsuz entegrasyonudur. Bu özellik, API'nizin kullanılabilirliğini artırır ve API'nizi kullanan geliştiriciler için daha iyi bir deneyim sağlar. İşte FastAPI'nin bunu nasıl başardığına ve sorgu parametreleriniz için belgeleri nasıl geliştirebileceğinize daha yakından bir bakış.
OpenAPI Nedir?
OpenAPI, API'nizin yeteneklerini tanımlamanın standart bir yolunu sağlayan, API'ler oluşturmaya yönelik bir spesifikasyondur. Hem insanların hem de makinelerin, kaynak koduna erişmeden veya başka herhangi bir belge görmeden bir hizmetin yeteneklerini anlamasını sağlar. FastAPI, API uç noktalarınız için etkileşimli belgeleri otomatik olarak oluşturmak için bu spesifikasyondan yararlanır.
FastAPI Belgeleri Nasıl Oluşturur
FastAPI uygulamanızı ve uç noktalarını tanımladığınızda, FastAPI otomatik olarak işlev imzalarına ve tanımladığınız parametrelerin türlerine göre bir OpenAPI şeması oluşturur. Bu şema şunları içerir:
- Uç nokta yolları: Uygulamanızda tanımladığınız rotalar.
- HTTP yöntemleri: Her uç noktayla ilişkili yöntemler (GET, POST, PUT, DELETE, vb.).
- Parametreler: Türleri, varsayılan değerleri ve kısıtlamaları dahil olmak üzere hem yol hem de sorgu parametreleri.
- Yanıt modelleri: Her uç nokta için beklenen yanıt biçimi.
FastAPI ile Etkileşimli Belgeler Nasıl Kullanılır
FastAPI, kutudan çıktığı gibi iki etkileşimli belge arayüzü sağlar:
- Swagger UI:
/docsadresinden erişilebilir, bu arayüz kullanıcıların API'nizin uç noktalarını keşfetmelerine, istek ve yanıt biçimlerini görüntülemelerine ve hatta uç noktaları doğrudan tarayıcıdan test etmelerine olanak tanır. - ReDoc:
/redocadresinde mevcuttur, bu arayüz API belgelerinizin daha ayrıntılı ve yapılandırılmış bir görünümünü sağlar, çeşitli uç noktaları ve parametrelerini gezinmeyi ve anlamayı kolaylaştırır.
Her iki arayüz de, belgelerinizin kodunuzla her zaman güncel olmasını sağlayan, FastAPI tarafından oluşturulan OpenAPI şemasına göre otomatik olarak oluşturulur.
Sorgu Parametreleri için Belgeleri Geliştirme
FastAPI sorgu parametreleriniz için temel belgeler oluştururken, ayrıntılı açıklamalar, örnekler ve ek meta veriler sağlayarak daha da geliştirebilirsiniz. İşte nasıl:
- Açıklayıcı Metin: Her sorgu parametresinin ne işe yaradığını net bir şekilde açıklamak için
Queryişlevindekidescriptionparametresini kullanın. Bu, özellikle API'nize aşina olmayan kullanıcılar için faydalıdır.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: str | None = Query(default=None, description="Öğeleri filtrelemek için arama terimi."),
skip: int = Query(default=0, ge=0, description="Atlanacak öğe sayısı."),
limit: int = Query(default=10, le=100, description="Döndürülecek maksimum öğe sayısı.")
):
return {"q": q, "skip": skip, "limit": limit}2. Örnekler: Sorgu parametrelerinizin nasıl kullanılabileceğini göstermek için örnekler sağlayın. Bu, özellikle karmaşık parametreler veya izlenmesi gereken belirli biçimler olduğunda kullanışlıdır.
@app.get("/items/")
async def read_items(
q: str | None = Query(default=None, description="Öğeleri filtrelemek için arama terimi.", example="elma"),
skip: int = Query(default=0, ge=0, description="Atlanacak öğe sayısı.", example=5),
limit: int = Query(default=10, le=100, description="Döndürülecek maksimum öğe sayısı.", example=20)
):
return {"q": q, "skip": skip, "limit": limit}3. Doğrulama Kısıtlamaları: Sorgu parametreleriniz için herhangi bir doğrulama kısıtlamasını açıkça belirtin. Bu, minimum ve maksimum değerleri, uzunluk kısıtlamalarını ve belirli biçimleri içerir. FastAPI bu doğrulamaları otomatik olarak işler, ancak bunları belgelemek, kullanıcıların sınırları anlamasına yardımcı olur.
4. Tür Açıklamaları: Sorgu parametreleriniz için uygun tür açıklamaları kullanın. FastAPI, belgelerde beklenen veri türlerini otomatik olarak oluşturmak için bu açıklamaları kullanır, bu da kullanıcıların ne tür veriler sağlamaları gerektiğini anlamalarına yardımcı olur.
5. İlgili Parametreleri Gruplandırma: API'niz birkaç ilgili sorgu parametresine sahipse, bunları mantıksal olarak gruplandırmayı düşünün. Bu, kullanıcıların parametrelerin birbiriyle nasıl etkileşimde bulunduğunu ve hangi kombinasyonların geçerli olduğunu anlamalarına yardımcı olabilir.
Geliştirilmiş Belgelerin Faydaları
- Geliştirilmiş Kullanılabilirlik: İyi belgelenmiş sorgu parametreleri, geliştiricilerin API'nizle nasıl etkileşim kuracaklarını anlamalarını kolaylaştırır. Bu, öğrenme eğrisini azaltır ve benimsemeyi artırır.
- Azaltılmış Destek Talepleri: Açık belgeler, yaygın soruları yanıtlamaya yardımcı olabilir ve API'nizi nasıl kullanacaklarını anlamaya çalışan kullanıcılardan aldığınız destek taleplerinin sayısını azaltabilir.
- Daha Hızlı Geliştirme: Geliştiriciler, uygulamalar oluştururken belgelere hızlı bir şekilde başvurabilir, bu da daha hızlı entegrasyon ve geliştirme döngülerine yol açar.
- Artan API Benimsenmesi: Kapsamlı ve kullanıcı dostu belgeler, API'nizi kullanmak için daha fazla geliştirici çekebilir, genel başarısını ve erişimini artırabilir.
- Tutarlılık: Otomatik belgeler, API belgelerinizin gerçek uygulamayla tutarlı olmasını sağlar ve bu da kafa karışıklığına yol açabilecek tutarsızlıkları azaltır.
FastAPI Sorgu Parametreleri için Gelişmiş Teknikler
FastAPI Sorgu Parametreleri için Enums Kullanma
Python Enums kullanarak FastAPI sorgu parametrelerini önceden tanımlanmış bir değer kümesiyle kısıtlayabilirsiniz. Bu, yalnızca belirli seçenekleri kabul etmesi gereken parametreler için kullanışlıdır:
from enum import Enum
class ItemType(str, Enum):
fruit = "meyve"
sebze = "sebze"
sütürünleri = "sütürünleri"
@app.get("/items/")
async def read_items(item_type: ItemType):
return {"item_type": item_type}Bu örnekte, item_type sorgu parametresi yalnızca ItemType Enum'unda tanımlanan değerlerden biri olabilir. İstemci geçersiz bir değer sağlarsa, FastAPI 422 hatası döndürecektir.
Sorgu Parametresi Bağımlılıkları
FastAPI, birden çok uç nokta arasında mantığı yeniden kullanmanıza yardımcı olabilecek sorgu parametreleri için bağımlılıklar oluşturmanıza olanak tanır. Sorgu parametrelerine göre bir değer döndüren bir bağımlılık işlevi tanımlayabilirsiniz:
from fastapi import Depends
def query_param_dependency(q: str | None = None):
return q if q else "varsayılan"
@app.get("/items/")
async def read_items(q: str = Depends(query_param_dependency)):
return {"q": q}Bu örnekte, query_param_dependency işlevi, q sorgu parametresinin sağlanıp sağlanmadığını kontrol eder. Değilse, varsayılan bir değer döndürür. Bu yaklaşım, kodun yeniden kullanılabilirliğini teşvik eder ve uç nokta işlevlerinizi temiz tutar.
FastAPI Sorgu Parametreleri için Hata İşleme
FastAPI, sorgu parametreleriyle ilgili hataları otomatik olarak işler. Gerekli bir sorgu parametresi eksikse veya bir parametre doğrulama başarısız olursa, FastAPI ayrıntılı bir hata mesajıyla 422 İşlenemeyen Varlık yanıtı döndürür. İstisna işleyicileri kullanarak hata işlemesini özelleştirebilirsiniz:
from fastapi import HTTPException
@app.get("/items/")
async def read_items(q: str | None = Query(default=None)):
if q is None:
raise HTTPException(status_code=400, detail="Sorgu parametresi 'q' gereklidir.")
return {"q": q}Bu örnek, gerekli bir sorgu parametresi sağlanmadığında özel bir HTTP istisnası nasıl yükseltilir gösterir. Bu yaklaşım, istemcilere daha bilgilendirici hata mesajları sağlamanıza olanak tanır.
FastAPI Sorgu Parametrelerini Test Etme
Sorgu parametrelerinizin beklendiği gibi çalıştığından emin olmak için FastAPI uygulamanızı test etmek çok önemlidir. FastAPI uç noktalarınızda testler yapmak için httpx kitaplığını kullanabilirsiniz. İşte bir örnek:
import httpx
import pytest
@pytest.mark.asyncio
async def test_read_items():
async with httpx.AsyncClient() as client:
response = await client.get("http://localhost:8000/items/?q=test&skip=0&limit=10")
assert response.status_code == 200
assert response.json() == {"q": "test", "skip": 0, "limit": 10}Bu testte, sorgu parametreleriyle /items/ uç noktasına bir GET isteği gönderiyoruz ve yanıtın beklendiği gibi olduğunu iddia ediyoruz. Test, API'nizin FastAPI sorgu parametrelerini işlerken doğru davrandığından emin olmak için geliştirme sürecinin önemli bir parçasıdır.
Sonuç
FastAPI sorgu parametreleri, API uç noktalarınıza URL aracılığıyla ek veri geçirmenize olanak tanıyan güçlü bir özelliktir. FastAPI ile API'ler oluştururken esneklik, kullanılabilirlik ve performans avantajları sağlarlar. Bu kılavuzda, ayrıntılı örnekler kullanarak FastAPI sorgu parametrelerini nasıl tanımlayacağımızı, bunlara nasıl erişeceğimizi, nasıl doğrulayacağımızı ve nasıl belgeleyeceğimizi inceledik. İsteğe bağlı ve gerekli parametreler, birden çok değer, karmaşık türler ve otomatik belge oluşturma gibi konuları ele aldık. Ayrıca, gelişmiş teknikleri, hata işlemeyi, test etmeyi ve yaygın tuzakları da tartıştık. FastAPI sorgu parametrelerinden yararlanarak, birden çok özel uç noktaya ihtiyaç duymadan çeşitli filtreleme, sıralama ve sayfalama gereksinimlerini karşılayabilen daha esnek ve kullanıcı dostu API'ler oluşturabilirsiniz. API'nizin kullanıcılarınız için kullanımı kolay ve iyi belgelenmiş olmasını sağlamak için uygun parametre türlerini, doğrulamaları ve açıklamaları seçmeyi unutmayın. FastAPI'nin güçlü sorgu parametresi yetenekleri, API'nizin işlevselliğini ve kullanılabilirliğini önemli ölçüde artırabilir ve onu modern web uygulamaları için mükemmel bir seçim haline getirebilir.
FastAPI Hakkında Ek Kaynaklar
FastAPI sorgu parametreleri hakkındaki anlayışınızı daha da geliştirmek için aşağıdaki kaynakları keşfetmeyi düşünün:
- FastAPI Belgeleri: Resmi FastAPI belgeleri, sorgu parametreleri ve diğer özellikler hakkında kapsamlı bilgiler sağlar.
- FastAPI GitHub Deposu: Kaynak kodu, örnekler ve topluluk katkıları için FastAPI GitHub deposuna göz atın.
- FastAPI Eğitimleri: Bilgi ve becerilerinizi derinleştirmek için FastAPI'ye odaklanan çevrimiçi eğitimler ve kurslar arayın.
FastAPI sorgu parametreleri için bu en iyi uygulamaları ve teknikleri izleyerek, 2024 ve ötesinde kullanıcılarınızın ihtiyaçlarını karşılayan sağlam ve verimli API'ler oluşturabilirsiniz.
