Python FastAPI ile API Nasıl Geliştirilir?

FastAPI nedir, neden tercih edilir?

FastAPI, Python ile API geliştirmek için kullanılan modern bir web çatısıdır. Tip ipuçlarını (type hint) kullanarak istek ve yanıt yapılarını tanımlamanıza izin verir; bu tanımlar hem veri doğrulamayı hem de otomatik API dokümantasyonunu besler. Asenkron çalışmayı doğal olarak destekler, bu da çok sayıda eşzamanlı isteği karşılayan servisler için uygundur.

Tercih edilme nedenleri şunlardır: az kodla net bir API yazılabilmesi, hata mesajlarının anlaşılır olması ve dokümantasyonun kod yazıldıkça kendiliğinden oluşması. Bu özellikler, hem küçük servislerde hem de mikroservis mimarilerinde hızlı ilerlemeyi sağlar.

İlk API: yol, işlem ve parametre

Bir FastAPI uygulaması bir Python fonksiyonuyla başlar. Fonksiyonu bir yola ve bir HTTP yöntemine bağlarsınız: örneğin ürün listesini döndüren bir okuma işlemi ya da yeni bir kayıt oluşturan bir yazma işlemi. Yol parametreleri (bir kaydın kimliği gibi) ve sorgu parametreleri (filtre, sayfalama gibi) fonksiyon argümanları olarak tanımlanır; çatı gelen veriyi belirtilen türe çevirir ve uyumsuzsa hata döndürür.

Uygulamayı çalıştırdığınızda otomatik üretilen etkileşimli dokümantasyon sayfasından uç noktaları tarayıcıdan deneyebilirsiniz. Bu, geliştirme sırasında hızlı geri bildirim sağlar.

Pydantic ile veri modelleme ve doğrulama

İstek gövdesi ve yanıt yapıları Pydantic modelleriyle tanımlanır. Model, alanları ve türlerini belirtir; alan kısıtları (zorunlu, aralık, biçim) doğrulama kuralı olur. Gelen veri modele uymuyorsa istek, iş mantığına ulaşmadan açıklayıcı bir hatayla reddedilir.

Giriş modeli ile çıkış modelini ayırmak iyi bir uygulamadır. Örneğin kullanıcı oluştururken parola alanı giriş modelinde bulunur ama yanıt modelinde asla yer almaz. Böylece hassas alanların yanlışlıkla dışarı sızması önlenir.

Bağımlılık enjeksiyonu ve router yapısı

Uygulama büyüdükçe kodu düzenli tutmak gerekir. FastAPI'de router'lar, ilgili uç noktaları (kullanıcılar, siparişler gibi) ayrı dosyalarda gruplamaya yarar. Bağımlılık enjeksiyonu ise veritabanı oturumu, geçerli kullanıcı ya da ortak ayarlar gibi tekrar eden ihtiyaçları fonksiyonlara parametre olarak sağlar.

Bu yapı, test yazmayı da kolaylaştırır: bağımlılığı test sırasında sahte bir sürümle değiştirebilirsiniz. Katmanları net ayırmak (uç nokta, iş mantığı, veri erişimi) projenin bakımını uzun vadede kolaylaştırır.

Veritabanı entegrasyonu, kimlik doğrulama ve arka plan görevleri

Veritabanı erişimi için çoğunlukla bir ORM kullanılır; SQLAlchemy yaygın bir tercihtir ve asenkron çalışmayı destekler. Her istek kendi veritabanı oturumunu bağımlılık olarak alır ve iş bitince kapatır. Şema değişiklikleri için taşıma (migration) aracı kullanmak, ortamlar arasında tutarlılık sağlar.

Kimlik doğrulamada jeton tabanlı yöntemler yaygındır; kullanıcı giriş yapar, bir jeton alır ve sonraki isteklerde bunu sunar. Tarayıcıdan gelen isteklerde CORS ayarı, hangi kaynakların API'ye erişebileceğini belirler. E-posta göndermek gibi yanıtı geciktirmemesi gereken işler arka plan görevlerine alınır.

Örnek bir akış: ürün servisi için uç noktaları adım adım kurmak

Örneğin küçük bir ürün servisi yazdığınızı düşünün. İlk adımda ürünü temsil eden iki Pydantic modeli tanımlarsınız: oluşturma isteğinde kullanılan giriş modeli ve yanıtta dönen, kimlik alanı da içeren çıkış modeli. İkinci adımda bir router oluşturup listeleme, tek kayıt getirme, oluşturma, güncelleme ve silme uç noktalarını bu router altında toplarsınız.

Üçüncü adımda veritabanı oturumunu bir bağımlılık fonksiyonu olarak yazar, uç noktalara parametre olarak verirsiniz. Kayıt bulunamadığında "bulunamadı" durum koduyla açıklayıcı bir hata döndürür, geçersiz veride çatının otomatik ürettiği doğrulama hatasına güvenirsiniz. Dördüncü adımda listeleme uç noktasına sayfalama ve filtre parametreleri eklersiniz; böylece büyük veri kümeleri tek yanıtta dönmez.

Beşinci adımda her uç nokta için test istemcisiyle en az iki test yazarsınız: başarılı durum ve hatalı girdi durumu. Son adımda otomatik dokümantasyon sayfasını açıp uç noktaları elle denersiniz; ardından uygulamayı konteynere koyarsınız. Bu sırayı izlemek, küçük bir servisi bile bakımı kolay, test edilebilir ve belgesi hazır bir yapıya oturtur. Servis büyüdüğünde yeni kaynaklar için aynı kalıp tekrar edilir: model, router, bağımlılık, test.

Yanıt tasarımı ve hata sözleşmesi

İyi bir API yalnızca doğru veri dönmez, hata durumlarını da tutarlı anlatır. Uç noktalarda hangi durum kodunun ne zaman döneceğini önceden kararlaştırın: oluşturmada başarı için oluşturuldu kodu, bulunamayan kayıt için "bulunamadı" kodu, yetkisiz erişim için ilgili kimlik doğrulama ve yetki kodları. Hata gövdesinde makine tarafından işlenebilir bir hata türü ve insan tarafından okunabilir bir mesaj bulunması, istemci geliştiricilerin işini kolaylaştırır.

Çıkış modelini uç noktada açıkça belirtmek (yanıt modeli), hem dokümantasyonu doğru üretir hem de modelde olmayan alanların dışarı sızmasını engeller. Alan adlarını ve biçimlerini projenin her yerinde aynı tutun; tarih biçimi ve boş değer davranışı gibi ayrıntılar ekipler arası uyumsuzluğun ilk kaynaklarıdır.

Test, dokümantasyon ve yayına alma

API'nin her uç noktası için otomatik test yazmak, değişikliklerde gerilemeyi önler. FastAPI test istemcisi, sunucuyu ayağa kaldırmadan istek göndermeyi sağlar. Veritabanı bağımlılığını test veritabanıyla değiştirerek gerçekçi senaryolar sınanır.

Yayına almada uygulama bir konteyner içinde paketlenir ve bir uygulama sunucusuyla çalıştırılır. Ortam ayarları (gizli anahtarlar, veritabanı adresi) kodun dışında tutulur. Sağlık kontrolü uç noktası, dağıtım ve izleme sistemlerinin servisin durumunu anlamasını sağlar.

Sık yapılan hatalar ve Mindset programı

• Asenkron fonksiyon içinde engelleyen (bloklayan) çağrı yapmak: Tüm uygulama yavaşlar.
• Giriş ve çıkış modelini ayırmamak: Hassas alanlar yanıta sızabilir.
• Veritabanı oturumunu her yerde elle yönetmek: Bağımlılık enjeksiyonu kullanın.
• Gizli anahtarları koda yazmak.
• Test yazmadan yayına çıkmak.
• CORS'u gereğinden geniş açmak.

Mindset kataloğundaki Python ile Web Geliştirme (FastAPI) programı; "Python ve FastAPI Ekosistemi", "Pydantic ile Veri Modelleme ve Doğrulama", "Bağımlılık Enjeksiyonu ve Router Yapısı", "Veritabanı Entegrasyonu: SQLAlchemy ve Async", "Kimlik Doğrulama, Güvenlik ve CORS", "Asenkron Programlama ve Arka Plan Görevleri" ve "Test, Dokümantasyon ve Deployment" modüllerini içerir.