FastAPI, tip ipuçları, doğrulama ve otomatik OpenAPI dokümantasyonu sayesinde API'leri hızlıca oluşturmanızı sağlayan modern bir Python çerçevesidir. Temel bilgileri ve kullanım alanlarını öğrenin.
FastAPI, Python ile web API'leri hızlıca oluşturmak için kullanılan bir çerçevedir; temiz kod ve otomatik dokümantasyon sağlar. Küçük fonksiyonlar ("endpoint" olarak adlandırılır) yazarak API'nizin hangi verileri kabul ettiğini ve ne döndürdüğünü belirtirsiniz, FastAPI ise yönlendirme, doğrulama ve JSON yanıt üretimi gibi web altyapısını halleder.
API, bir yazılım parçasının başka bir yazılımla konuşmasını sağlayan URL'ler dizisidir.
Örneğin, telefonunuzdaki bir hava durumu uygulaması GET /weather?city=Berlin gibi bir URL çağırabilir. Sunucu sıcaklık ve tahmin gibi yapılandırılmış verilerle (genellikle JSON) cevap verir. Telefon uygulamasının sunucunun veritabanına doğrudan erişmesi gerekmez—sadece API'ye sorar ve sonucu gösterir.
FastAPI, bu URL'leri ve yanıtları Python ile oluşturmanıza yardımcı olur.
Başlamak için asenkron programlamada uzman olmanız gerekmez; basit endpointler yazıp zamanla daha gelişmiş desenleri benimseyebilirsiniz.
FastAPI, Python'da API oluştururken sık karşılaşılan sürtünmeyi azaltıyor.
Geleneksel API projeleri genellikle uzun kurulumlar ve çok sayıda "altyapı" ile başlar:
FastAPI'nin temel özellikleri bu sorunları doğrudan hedefler, böylece ekipler endpoint tasarımına daha fazla zaman ayırır, framework teferruatıyla daha az uğraşır.
FastAPI, Python tip ipuçlarına güçlü şekilde dayanır. Bir alanın int, opsiyonel veya bir liste gibi olduğunu belirttiğinizde, FastAPI bu bilgiyi girişleri doğrulamak ve çıktıları biçimlendirmek için kullanır.
Bu, kimlikleri bazen metin bazen sayı olarak ele alma gibi "string ağırlıklı" hataları azaltır ve fonksiyon imzalarına gömülü daha net beklentiler sağlar.
API şeması koddan türetildiği için FastAPI, etkileşimli dokümantasyonu otomatik olarak oluşturabilir (OpenAPI + Swagger UI/ReDoc). Bu, frontend geliştiricilerinin, QA'nın ve entegratörlerin endpointleri keşfetmesi, istek denemesi ve modelleri görmesi için önemli bir kolaylıktır.
FastAPI kötü tasarlanmış bir API'yi tek başına düzeltmez. Yine de iyi isimlendirme, versiyonlama, hata yönetimi ve güvenlik kararlarına ihtiyaç vardır. FastAPI size fikirden "iyi tanımlanmış API"ye daha az sürprizle ulaşma yolu sunar.
FastAPI, birkaç temel fikir üzerine kurulu olduğu için mantığı kavradığınızda sade hisseder. İç detayları ezberlemek zorunda değilsiniz—günlük kullanacağınız parçaları tanımanız yeterli.
Bir çerçeve sıfırdan başlamadan bir API oluşturmak için araçlar ve kurallar setidir. FastAPI, endpoint tanımlama, girdi okuma, çıktı döndürme, hata yönetimi ve kodu sürdürülebilir şekilde organize etme gibi ortak API görevleri için "altyapıyı" sağlar.
Routing bir URL ile HTTP metodunu bir Python kod parçasına eşleme işlemidir.
Örneğin GET /users "kullanıcıları listele" fonksiyonuna; POST /users ise "kullanıcı oluştur" fonksiyonuna yönlendirilebilir. FastAPI'de genellikle @app.get(...) ve @app.post(...) gibi dekoratörlerle rotalar tanımlanır; bu, API'nizin ne sunduğunu bir bakışta görmeyi kolaylaştırır.
Her API çağrısı bir istek (istemcinin gönderdiği) ve bir yanıt (sunucunun döndürdüğü) içerir.
FastAPI size yardımcı olur:
/users/{id}), sorgu dizesini (?page=2), başlıkları ve istek gövdesini okumak200, 201, 404) yapılandırılmış JSON yanıtları döndürmekFastAPI ASGI üzerinde çalışır; bu, Python web sunucuları için modern bir standarttır. Pratikte bu, FastAPI'nin çok sayıda bağlantıyı verimli şekilde ele alacak şekilde tasarlandığı ve uzun ömürlü bağlantılar (ör. WebSocket'ler) gibi özellikleri destekleyebileceği anlamına gelir—bunu düşük seviyeli ağ yönetimi yapmadan kullanabilirsiniz.
Python tip ipuçları (ör. str, int, list[Item]) FastAPI'de sadece dokümantasyon değildir—ana girdi olarak kullanılır. FastAPI bunları beklediğiniz veriyi anlamak, gelen değerleri doğru tiplere dönüştürmek ve daha belirgin, öngörülebilir API'ler oluşturmak için kullanır.
Pydantic modelleri verinin şeklini (alanlar, tipler, opsiyonel değerler) tek bir yerde tanımlamanıza izin verir. FastAPI bu modelleri gelen JSON'u doğrulamak, hatalı girdileri yararlı hata mesajlarıyla reddetmek ve çıktıyı tutarlı şekilde serileştirmek için kullanır—böylece istemciler dağınık veri gönderse bile API güvenilir davranır.
FastAPI uygulamaları endpoint'ler etrafında kurulur: bir URL yolu artı bir HTTP yöntemi. Endpoint'i istemcinin "ne istediği" ve "nasıl istediği" olarak düşünebilirsiniz. Örneğin, bir istemci kullanıcı listesini almak için GET /users isteği yapabilir veya bir kullanıcı oluşturmak için POST /users isteği gönderebilir.
Bir yol rotadır, yöntem ise eylemdir:
GET /products → veri alPOST /products → veri göndererek bir şey oluşturPUT /products/123 → bir şeyi değiştir/yerine koyDELETE /products/123 → bir şeyi silFastAPI yolun bir parçası olan veriyi ve isteğe bağlı filtreleri ayırır.
GET /users/42 → 42 kullanıcı ID'sidir.? sonrası eklenir, genellikle isteğe bağlıdır.
GET /users?limit=10&active=true → limit ve active sonuçları kontrol eder.İstemci yapılandırılmış veri (çoğunlukla JSON) gönderdiğinde bu istek gövdesinde olur; genellikle POST veya PUT ile kullanılır.
Örnek: POST /orders ve gövde olarak { "item_id": 3, "quantity": 2 } gönderme.
FastAPI düz Python objeleri (sözlükler gibi) döndürebilir, ancak en iyi halini bir yanıt modeli tanımladığınızda gösterir. Bu model bir sözleşme gibi davranır: alanlar tutarlı biçimde şekillenir, fazladan veri filtrelenebilir ve tipler zorlanır. Sonuç, istemcilerin ne bekleyeceğini bildiği daha temiz API'lerdir.
"Async" (eşanlı olmayan) bekleme süresi fazla olan durumlarda API'nizin istekleri verimli şekilde ele almasını sağlayan bir yaklaşımdır.
Bir barista müşterileri aldığını düşünün. Espresso makinesi çalışırken yerinde bekleyip hiçbir şey yapmasalardı, daha az müşteri servis edilir. Daha iyi bir yaklaşım: kahveyi başlat, sonra makine çalışırken diğer siparişi al. Async tam olarak bunun gibi çalışır. FastAPI uygulamanız, ağ isteği veya veritabanı sorgusu gibi yavaş bir işlem başlattığında beklerken diğer gelen istekleri işleyebilir.
Async, çok fazla I/O yapan (beklemeye dayalı) işlemlerde etkilidir. Yaygın örnekler:
Bu operasyonlar sıkça bekleme içeriyorsa, async iş hacmini artırabilir ve yoğunluk altında isteklerin kuyrukta birikmesini azaltabilir.
Async her şeyi hızlandıran bir sihirli düğme değildir. Endpointiniz çoğunlukla CPU-ağırlıklıysa—örneğin büyük resim boyutlandırma, veri bilimi hesaplamaları veya büyük yükleri şifreleme—async hesaplamayı daha hızlı yapmaz. Bu durumlarda arka plan işçileri, işlem havuzları veya yatay ölçekleme gibi farklı taktikler gerekir.
FastAPI'yi kullanmak için her şeyi yeniden yazmanız gerekmez. Normal (senkron) route fonksiyonları yazabilirsiniz ve FastAPI bunları sorunsuz çalıştırır. Birçok proje her iki stili karıştırır: basit endpointleri senkron tutar ve veritabanı çağrıları veya dış HTTP isteklerinde async def kullanılır.
Doğrulama, dış dünya ile kodunuz arasındaki kontrol noktasıdır. Bir API giriş kabul ettiğinde (JSON gövdesi, sorgu parametreleri, yol parametreleri) verinin eksiksiz, doğru tipte ve makul sınırlar içinde olduğundan emin olmak istersiniz—bunu yapmadan önce veritabanına yazma, başka servisi çağırma veya iş mantığını tetikleme istemezsiniz.
FastAPI bu iş için Pydantic modellerine dayanır. "İyi veri"nin nasıl görünmesi gerektiğini bir kez tanımlarsınız ve FastAPI otomatik olarak:
Eğer bir istemci yanlış biçimde veri gönderirse, FastAPI 422 Unprocessable Entity ile ve hangi alanın neden hatalı olduğunu belirten yapılandırılmış bir hata yükü ile cevap verir. Bu, istemci geliştiricilerinin istekleri hızla düzeltmesini sağlar.
Burada gerekli alanları, tipleri, min/max kısıtlarını ve formatları gösteren küçük bir model var:
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
age: int = Field(ge=13, le=120)
username: str = Field(min_length=3, max_length=20)
email olmalıdır.age bir tamsayı olmalıdır.age 13–120 ile sınırlandırılmıştır.EmailStr geçerli bir e-posta biçimini zorunlu kılar.Aynı modeller çıktıyı şekillendirmek için de kullanılabilir, böylece API yanıtlarınız istemciye dahili alanları kazara sızdırmaz. Python objelerini döndürürsünüz; FastAPI (Pydantic aracılığıyla) bunları doğru alan adları ve tiplerle JSON'a çevirir.
FastAPI'nin en pratik özelliklerinden biri, zaten yazdığınız koda dayalı olarak API dokümantasyonunu otomatik oluşturmasıdır.
OpenAPI, bir API'yi yapılandırılmış formatta (genellikle JSON) tanımlamanın standart yoludur. Şöyle bir "sözleşme" gibidir:
GET /users/{id})Makine tarafından okunabilir olduğu için araçlar bunu test istemcileri üretmek, istekleri doğrulamak ve ekipleri hizalamak için kullanabilir.
FastAPI iki insan dostu doküman sayfasını otomatik olarak sunar:
Tipik bir FastAPI projesinde bunları bulabilirsiniz:
/docs (Swagger UI)/redoc (ReDoc)Yol parametrelerinizi, istek modellerinizi, yanıt modellerinizi veya doğrulama kurallarınızı değiştirdiğinizde OpenAPI şeması (ve doküman sayfaları) otomatik güncellenir. Ayrı bir "doküman bakımı" adımına gerek kalmaz.
Bir FastAPI uygulaması küçük olabilir ve yine de "gerçek" hissi verir. Bir Python nesnesi olan appi tanımlarsınız, birkaç rota eklersiniz ve yerel sunucuda çalıştırıp tarayıcıda denersiniz.
En küçük kullanışlı örnek şöyle:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI"}
Hepsi bu: bir rota (GET /) JSON döndürüyor.
Daha API gibi hissettirmek için öğeleri bir listede saklayalım. Bu bir veritabanı değil—sunucu yeniden başlatıldığında veriler sıfırlanır—ama öğrenmek için ideal.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(name: str):
item = {"id": len(items) + 1, "name": name}
items.append(item)
return item
@app.get("/items")
def list_items():
return items
Şimdi şunları yapabilirsiniz:
POST /items?name=Coffee ile bir öğe ekleyinGET /items ile listeyi alınYaygın başlangıç yapısı:
main.py (appi ve rotaları oluşturur)requirements.txt veya pyproject.toml (bağımlılıklar)Genellikle:
uvicorn main:app --reload)http://127.0.0.1:8000 adresini açıp endpointleri deneyinFastAPI "bağımlılıklar"ı, endpointlerin işini yapması için gereken ortak girdilerdir—ör. veritabanı oturumu, oturum açmış kullanıcı, uygulama ayarları veya ortak sorgu parametreleri. Bunları her route'ta elle oluşturmak ve ayrıştırmak yerine bir kez tanımlar ve FastAPI'nin ihtiyaç duyulan yere sağlamasını sağlarsınız.
Bir bağımlılık genellikle bir değer döndüren fonksiyon (veya sınıf)tır. FastAPI onu çağırır, hangi parametrelere ihtiyaç duyduğunu anlar ve sonucunu path operation fonksiyonunuza enjekte eder.
Buna bağımlılık enjeksiyonu denir, ancak şöyle düşünebilirsiniz: "İhtiyacınızı belirtin, FastAPI onu bağlar."
Bağımlılıklar olmadan her endpointte şunları yapıyor olabilirsiniz:
Bağımlılıklar ile bu mantığı merkezileştirirsiniz. Daha sonra veritabanı oturumu oluşturma veya geçerli kullanıcıyı yükleme değiştiğinde birden fazla endpointi değil, tek bir yeri güncellersiniz.
page/limit ayrıştırma ve doğrulamasını yeniden kullanmaBirçok FastAPI uygulamasında göreceğiniz kavramsal desen şöyle:
from fastapi import Depends, FastAPI
app = FastAPI()
def get_settings():
return {"items_per_page": 20}
@app.get("/items")
def list_items(settings=Depends(get_settings)):
return {"limit": settings["items_per_page"]}
Depends(...) ile bağımlılığı bildirirsiniz ve FastAPI sonucunu endpoint parametrenize geçirir. Aynı yaklaşım daha karmaşık yapı taşları için de (ör. get_db() veya get_current_user()) çalışır; API büyüdükçe kodunuzu temiz tutar.
FastAPI API'nizi otomatik olarak güvence altına almaz—şemayı seçip endpoint'lere bağlamanız gerekir. İyi haber: FastAPI, bağımlılık sistemi aracılığıyla yaygın güvenlik desenlerini uygulamayı kolaylaştıran yapı taşları sağlar.
Kimlik doğrulama cevaplar: "Sen kimsin?" Yetkilendirme cevaplar: "Ne yapmana izin var?"
Örnek: bir kullanıcı doğrulanmış (geçerli token) olabilir fakat admin-only route'a erişme yetkisi olmayabilir.
X-API-Key). Rotasyon ve iptal politikasını yönetin.FastAPI bu desenleri fastapi.security gibi yardımcılarla destekler ve OpenAPI içinde temizce dokümante eder.
Kullanıcı parolası saklıyorsanız, asla düz metin saklamayın. Tuzlu, yavaş bir hash kullanın (örn. bcrypt/argon2). Ayrıca hız sınırlama ve hesap kilitleme politikalarını düşünün.
Güvenlik detaylarla ilgilidir: token depolama, CORS ayarları, HTTPS, gizli anahtar yönetimi ve her hassas endpointte doğru yetkilendirme kontrolleri. Dahili yardımcıları bir başlangıç noktası olarak kabul edin ve üretime geçmeden önce yaklaşımınızı incelemeler ve testlerle doğrulayın.
Test etmek, FastAPI'nin "makinemde çalışıyor" sözünü gerçekten güvenilir hale getirir. İyi haber: FastAPI Starlette üzerine kurulu olduğu için güçlü test araçlarını az ayar ile kullanabilirsiniz.
Birim testleri küçük parçaları hedefler: bir değer hesaplayan fonksiyon, geçerli kullanıcıyı yükleyen bağımlılık veya veritabanıyla konuşan bir servis metodu (genellikle mocklanır).
Entegrasyon testleri API'yi uçtan uca çalıştırır: bir endpointi çağırır ve tam HTTP yanıtını doğrular. Bu testler yönlendirme hatalarını, bağımlılık zinciri sorunlarını ve doğrulama problemlerini yakalar.
Sağlıklı bir test paketi genellikle daha fazla birim testi (hızlı) ve daha az sayıda entegrasyon testi (daha yüksek güven) içerir.
FastAPI uygulamaları Starlette'in TestClient'i kullanılarak "istemci gibi" test edilebilir; bu, uygulamanıza işlem içinde istek gönderir—sunucu gerekmez.
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_healthcheck():
r = client.get("/health")
assert r.status_code == 200
Kullanıcıların ve diğer sistemlerin güvendiği şeyleri test edin:
Tahmin edilebilir veriler kullanın, dış servisleri izole edin (mock veya test DB kullanın) ve testler arasında paylaşılan durumdan kaçının. Hızlı testler çalıştırılır; yavaş olanlar genelde atlanır.
FastAPI uygulamasını canlıya almak çoğunlukla doğru "çalıştırıcı"yı seçmek ve birkaç üretim gerekliliğini eklemekle ilgilidir.
uvicorn main:app --reload ile çalıştırırken geliştirme ayarlarını kullanırsınız: otomatik yeniden yükleme, ayrıntılı hatalar ve kullanım kolaylığını önceliklendiren ayarlar.
Üretimde genellikle Uvicorn reload kapalı çalıştırılır; sıklıkla bir süreç yöneticisi (ör. Gunicorn ile Uvicorn worker'ları) veya ters proxy arkasına alınır. Amaç istikrardır: kontrollü yeniden başlatmalar, öngörülebilir performans ve daha güvenli varsayılanlar.
Yaygın bir desen:
Bu, tek bir kod tabanının farklı ortamlara düzenleme yapmadan dağıtılmasını sağlar.
"Tamam" demeden önce şunların olduğundan emin olun:
/health gibi endpointler.Yerelden üretime geçerken API sözleşmenizi standartlaştırmak yardımcı olur. Bazı ekipler FastAPI'nin OpenAPI çıktısını otomatik iş akışlarına bağlar—ör. istemciler üretmek, CI'de istekleri doğrulamak ve tutarlı dağıtım. Araçlar arasında Koder.ai gibi platformlar bu aşamaya uyum sağlayabilir: sohbet üzerinden oluşturduğunuz API'yi tanımlayıp hızlıca endpoint ve modeller üretebilir, ardından çıktıyı normal inceleme/dağıtım hattına aktarabilirsiniz.
FastAPI, Python'da temiz, modern bir şekilde REST API'leri oluşturmak istediğinizde güçlü bir seçenektir—özellikle istek/yanıt modellerinin açık ve API büyüdükçe öngörülebilir davranışın önemli olduğu durumlarda.
FastAPI genellikle şu durumlarda çok iyi işler:
FastAPI her zaman en basit cevap değildir:
FastAPI pratikte çok hızlı olabilir, ancak hız veritabanı çağrılarınız, ağ gecikmeleri ve iş mantığınızın verimliliğine bağlıdır. Tipik API iş yüklerinde iyi throughput ve düşük gecikme bekleyebilirsiniz—ancak çerçeve tek başına yavaş I/O veya verimsiz sorguları "düzeltmez".
FastAPI uygun görünüyorsa, bir sonraki odak noktalarınız route desenleri, Pydantic modelleri, veritabanı entegrasyonu, arka plan görevleri ve temel kimlik doğrulama olmalıdır.
Pratik bir yol, küçük bir endpoint seti oluşturmak, sonra yeniden kullanılabilir bağımlılıklar ve testlerle genişletmektir. Erken aşamada (rota, model ve ilk dağıtıma hazır yapıyı) hızlandırmak için sohbet tabanlı bir taslak akışı kullanmak işinizi kolaylaştırabilir—örneğin endpointleri planlayıp tek bir şemadan iterasyon yapmak. Bu alanda Koder.ai yardımcı olabilir: sohbetten prototip oluşturup üretilmiş kodu standart bir inceleme/dağıtım hattına aktarabilirsiniz.
FastAPI, minimal tekrar gerektiren bir Python web çerçevesidir. Endpoint fonksiyonları (ör. @app.get("/users")) yazarsınız ve FastAPI yönlendirme, istek ayrıştırma, doğrulama ve JSON yanıtları ile ilgilenir.
Önemli bir avantaj, tip ipuçlarınızın ve Pydantic modellerinizin API'nin kabul ettiği ve döndürdüğü şeyler için açık bir sözleşme görevi görmesidir.
API, başka yazılımların veri alışverişi yapması için çağırabileceği bir dizi URL'dir.
Örneğin, bir istemci GET /weather?city=Berlin isteğiyle hava durumunu isteyebilir ve sunucu yapılandırılmış JSON ile cevap verir. İstemcinin veritabanına doğrudan erişmesi gerekmez—sadece API'yi kullanır.
Yönlendirme, bir HTTP yöntemi + yolu bir Python fonksiyonuna eşler.
FastAPI'de genellikle dekoratörler kullanırsınız:
@app.get("/items") okuma işlemleri için@app.post("/items") oluşturma işlemleri için@app.put("/items/{id}") güncelleme/yerine koyma içinYol (path) parametreleri URL yapısının bir parçasıdır ve genellikle belirli bir kaynağı tanımlar (zorunludur).
GET /users/42 → 42 bir yol parametresidirSorgu (query) parametreleri ? işaretinden sonra eklenir ve genellikle isteği filtrelemek veya kontrol etmek için isteğe bağlı kullanılır.
Pydantic modelleri, verinin şeklini ve kurallarını (tipler, zorunlu alanlar, kısıtlar) tanımlar. FastAPI bunları kullanarak:
Doğrulama başarısız olursa FastAPI genellikle 422 Unprocessable Entity döner ve hangi alanın neden hatalı olduğunu gösterir.
FastAPI, endpoint'lerinizden, tip ipuçlarından ve modellerinizden otomatik olarak bir OpenAPI şeması üretir.
Genellikle ücretsiz olarak interaktif dokümanlar elde edersiniz:
/docs altında/redoc altındaŞema koddan türetildiği için dokümanlar, parametreleri ve modelleri değiştirdiğinizde otomatik olarak güncellenir.
İstek beklerken geçen sürelerin yoğun olduğu durumlarda async def kullanın (veritabanı çağrıları, dış HTTP istekleri, dosya/nesne depolama erişimi gibi).
Aynı zamanda şunlar için def (senkron) kullanın:
Aynı uygulama içinde senkron ve asenkron endpointleri karıştırmak yaygındır.
Bağımlılıklar (dependencies), FastAPI'nin endpointlere Depends() ile enjekte ettiği yeniden kullanılabilir "yapı taşları"dır.
Yaygın kullanım alanları:
Bu, tekrarları azaltır ve çapraz kesen mantığı tek bir yerde merkezileştirir.
FastAPI API'nizi otomatik olarak güvenli hale getirmez—bir yaklaşım seçip endpoint'lere uygulamanız gerekir.
Yaygın desenler:
Ayrıca temel güvenlik uygulamaları şunlardır:
Test için FastAPI/Starlette'in TestClient'ini kullanarak uygulamanızı işlem içinde çağırabilirsiniz (sunucu gerektirmez).
Pratik olarak kontrol etmeniz gerekenler:
Dağıtım için genellikle bir ASGI sunucusu (ör. Uvicorn) çalıştırılır; üretimde ek olarak günlükleme, sağlık kontrolleri ( gibi), zaman aşımı ayarları ve çevreye göre yapılandırma eklemelisiniz.
@app.delete("/items/{id}") silme içinBu, API yüzeyinizi koddan doğrudan taramayı kolaylaştırır.
GET /users?limit=10&active=true → limit, active sorgu parametreleridir/health