API, iki programın konuştuğu dildir; Python'da bu dili en akıcı konuşan çerçeve FastAPI'dir. Bir mobil uygulama, bir web arayüzü ve bir veritabanı aynı veriyi paylaşmak zorunda kaldığında arada duran şey tam olarak budur — doğru tasarlanmış bir servis, yıllarca değişmeden çalışmaya devam eder; yanlış tasarlanmış bir servis, ilk büyük değişiklikte herkesi kilitler.
Bu rehberde REST'in temel kurallarını, FastAPI ile ilk servisin satır satır yazımını, Pydantic ile girdi doğrulamasını, hata yönetimini, otomatik OpenAPI dokümantasyonunu, test yazımını ve yayınlama akışını ele alıyoruz. Python temelleri için Python Nedir? rehberimiz; aynı çatı altında site kurmak isteyenler için Flask ile web sitesi rehberimiz doğrudan tamamlayıcınızdır.
REST nedir: beş kural
REST, bir mimari stildir, kütüphane değil. Bir servisi REST yapan beş kural vardır:
| Kural | Ne demek | İyi örnek | Kötü örnek |
|---|---|---|---|
| Adresleme | Her kaynak bir URI ile çağrılır | /urunler/42 | /urunGetir?id=42 |
| HTTP metodu | Eylem metotla taşınır | DELETE /urunler/42 | POST /urunSil |
| Durumsuzluk | Her istek kendine yeter | Token başlıkta taşınır | Sunucuda oturum değişkeni |
| Temsil | Veri JSON olarak taşınır | {"ad":"Kitap"} | HTML gövdesine gömülü veri |
| Stateless cache | Yanıtlar önbelleklenebilir | ETag başlığı | Her istekte değişen çıktı |
En sık yapılan hata, metot yerine URL ile eylem taşımaktır. Doğru yaklaşım şudur: URL kaynağı söyler, metot eylemi söyler. Kaynak çoğul isimlendirilir (/siparisler), eylem ise HTTP metoduyla ifade edilir. Bu basit disiplin, API'nizi okunur ve tahmin edilebilir yapar.
Hangi çerçeve: FastAPI, Flask ve Django karşılaştırması
| Özellik | FastAPI | Flask | Django REST Framework |
|---|---|---|---|
| Odak | API servisleri | Mikro web + API | Büyük ölçekli uygulama |
| Doğrulama | Pydantic, yerleşik | Elle veya eklenti | Serializer ile |
| Dokümantasyon | Otomatik OpenAPI | Eklenti gerekir | Eklenti gerekir |
| Performans | Çok yüksek (async) | Orta | Orta |
| Öğrenme eğrisi | Düşük-orta | Çok düşük | Yüksek |
Karar kuralı basit: yeni bir API servisi açacaksanız FastAPI; HTML üreten küçük bir siteye Flask; kullanıcı yönetimi ve admin paneli gerektiren büyük bir sisteme Django. Bu rehber boyunca FastAPI kullanıyoruz çünkü 2026 itibarıyla Python API geliştirme tarafında en hızlı yayılan çerçeve oldu; resmî başlangıç kılavuzuna FastAPI first steps sayfasından ulaşabilirsiniz.
Kurulum ve ilk servis
İki paket yeterlidir: FastAPI ve bir ASGI sunucusu (uygulamayı çalıştıran). Komut satırında:
pip install fastapi "uvicorn[standard]"
# app.py dosyasını oluşturun
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def ana_sayfa():
return {"mesaj": "Merhaba, bu bir API"}
Ardından çalıştırın:
uvicorn app:app --reload
Şimdi http://127.0.0.1:8000 adresine gidin, JSON yanıtını görün. --reload parametresi, dosya değiştiğinde sunucuyu kendiliğinden yeniden başlatır — geliştirme sırasında pratik, ancak canlı ortamda asla kullanılmaz.
Uç nokta tasarımı: kaynak ve metot
Örnek senaryo: bir ürün kataloğu. Kaynaklar çoğul, eylemler metotlarla:
| Metot | Uç nokta | Ne yapar | Başarı kodu |
|---|---|---|---|
GET | /urunler | Listeyi döndürür (sayfalı) | 200 |
GET | /urunler/42 | Tek kaydı döndürür | 200 / 404 |
POST | /urunler | Yeni kayıt oluşturur | 201 |
PUT | /urunler/42 | Kaydı tamamen günceller | 200 / 404 |
DELETE | /urunler/42 | Kaydı siler | 204 / 404 |
İki ayrıntı önemlidir. Birincisi: 201 (Created), POST'un doğru başarı kodudur, 200 değil. İkincisi: silme işleminde gövde boş döner (204). Bu küçük ayrımlar, API'nizi profesyonel yapan detaylardır.
Pydantic ile modelleme ve doğrulama
FastAPI'nin en güçlü yanı, girdiyi sizin yerinize doğrulamasıdır. Bir Pydantic modeli tanımladığınızda çerçeve, gelen JSON'u bu modele göre kontrol eder, uymayanı 422 koduyla reddeder ve hatayı açıklayıcı biçimde döndürür:
from pydantic import BaseModel, Field
class UrunOlustur(BaseModel):
ad: str = Field(min_length=2, max_length=100)
fiyat: float = Field(gt=0)
stok: int = Field(default=0, ge=0)
etiketler: list[str] = []
Bu model tek başına üç iş yapar: tip kontrolü, sınır denetimi ve dönüşüm. Gelen veride fiyat eksi değerse istek reddedilir; stok yoksa 0 kabul edilir; etiketler bir metin olarak gelirse listeye çevrilir. Doğrulama mantığını her uç noktada elle yazmak yerine modelde bir kez yazarsınız — bu, tekrar eden kodu ortadan kaldırır. Modellemenin tüm kuralları için Pydantic dokümanları referansınızdır.
Uç noktayı yazmak: uçtan uca akış
from fastapi import FastAPI, HTTPException
app = FastAPI()
veritabani: dict[int, dict] = {}
sonraki_id = 1
@app.post("/urunler", status_code=201)
def urun_olustur(veri: UrunOlustur):
global sonraki_id
kayit = {"id": sonraki_id, **veri.model_dump()}
veritabani[sonraki_id] = kayit
sonraki_id += 1
return kayit
@app.get("/urunler/{urun_id}")
def urun_getir(urun_id: int):
if urun_id not in veritabani:
raise HTTPException(status_code=404, detail="Ürün bulunamadı")
return veritabani[urun_id]
İlk sürüm için bellek içi sözlük yeterlidir; kalıcılık gerektiğinde aynı fonksiyonların içi değiştirilir, uç noktalar değişmez. Bu ayrım önemlidir: API sözleşmesi sabit kalır, altındaki mekanizma değişebilir. Müşteri tarafı (mobil uygulama, arayüz) yalnızca URL ve JSON formatını bilir.
Hata yönetimi: 422, 404 ve ötesi
| Kod | Anlamı | Ne zaman döner |
|---|---|---|
| 400 | Kötü istek | Semantik olarak anlamsız veri |
| 401 | Kimlik doğrulanmadı | Token yok veya geçersiz |
| 403 | Yetki yok | Giriş yapılmış ama erişim yasak |
| 404 | Bulunamadı | Kayıt yok ya da URL yanlış |
| 422 | Doğrulama hatası | Pydantic modeli reddetti |
| 429 | Çok fazla istek | Hız sınırı aşıldı |
| 500 | Sunucu hatası | Beklenmeyen istisna |
En sık yapılan iki hata: her şeyi 500 olarak döndürmek ve hata gövdesini boş bırakmak. İyi bir hata yanıtı üç alanı içerir: kod, açıklanabilir mesaj, izlenebilir kimlik. Sunucu tarafında gerçek ayrıntıyı günlüğe yazın, istemciye ise yeterli ve güvenli mesajı verin — veritabanı adı veya yığın izi asla dışarı sızmasın.
Bir diğer nokta: 401 ile 403'ü karıştırmamak. "Giriş yapmadın" (401) ile "giriş yaptın ama bu kayda erişimin yok" (403) aynı şey değildir; bunları doğru kullanmak, istemci tarafında doğru davranış üretir.
Otomatik dokümantasyon: OpenAPI
FastAPI, her uç noktayı tanımladığınız anda dokümantasyonu kendiliğinden üretir. /docs adresine gidin:
- İnsan için: denenebilir, etkileşimli bir arayüz — parametre girin, "Execute" deyin, canlı yanıtı görün
- Makine için:
/openapi.jsonüzerinden standart OpenAPI şeması — bu dosyadan istemci kodu üretilebilir
Bu, ayrı bir doküman yazma yükünü tamamen ortadan kaldırır: kod değiştiğinde doküman da değişir, çünkü ikisi aynı kaynaktan doğar. Şemanın resmî tanımı için OpenAPI 3.1 şartnamesine ve araç ekosistemi için Swagger spesifikasyonuna bakılabilir. Servis bir kez çalışır hâle geldiğinde, onu betiklerle kullanmak isteyenler için Python otomasyon rehberimiz; yanıtı CSV'ye döküp raporlamaya bağlamak isteyenler için Excel/CSV veri işleme rehberimiz bir sonraki adımdır.
Test yazmak: değişiklikten korkmayın
FastAPI, TestClient ile sunucuyu gerçekten başlatmadan istek atmanıza izin verir. Bu, testleri hızlı ve deterministik yapar:
from fastapi.testclient import TestClient
client = TestClient(app)
def test_urun_olustur():
r = client.post("/urunler", json={"ad": "Kitap", "fiyat": 120.0})
assert r.status_code == 201
assert r.json()["id"] == 1
def test_eksik_alan_red():
r = client.post("/urunler", json={"fiyat": -5})
assert r.status_code == 422
En az üç testi hep yazın: başarılı yol, geçersiz girdi, bulunamayan kayıt. Bunlar, API'nizin sözleşme tarafını korur. Testin kurulumu için json modülü dokümanı ve Python test ekosistemi başlangıç için yeterlidir. Servisten gelen veriyi kazıyarak toplamanız gerekirse web scraping rehberimiz aynı Python becerisini başka bir kapıda kullanır.
Yayınlama akışı: geliştirmeden canlıya
- Yerel doğrulama:
uvicorn app:appile çalıştırın,/docs'tan deneyin - Test: TestClient ile en az üç senaryo
- Ortam değişkenleri: anahtar, veritabanı adresi, port — kodda değil ortamda
- Sunucu: Uvicorn'u bir süreç yöneticisi (systemd, Docker) arkasına koyun
- Sınır: Dışa açmadan önce hız sınırı (429) ve kimlik doğrulama
- İzleme: İstek süresi, hata oranı, 5xx sayısı
Geliştirme sunucusu (--reload) ile üretim sunucusu arasında ciddi bir fark vardır: ikincisi çok süreçli çalışır, günlükleme yapar ve yeniden başlatmaları güvenlidir. Bu ayrımı atlamak, ilk trafik artışında beklenmeyen sonuçlar doğurur.
Sık yapılan 6 hata
| Hata | Sonuç | Doğrusu |
|---|---|---|
| URL'de eylem taşımak | Tahmin edilemez API | URL kaynak, metot eylem |
| Her şeyi 200 ile döndürmek | İstemci tarafında karmaşa | Gerçek HTTP kodları |
| Doğrulamayı elle yapmak | Dağınık, tekrar eden kod | Pydantic modeli |
| Açık uç noktada yetki yok | Veri sızıntısı | 401/403 kontrolü |
| Dokümanı elle güncellemek | Kodla uyumsuzluk | Otomatik OpenAPI |
| Testi sona bırakmak | Kırılma fark edilmez | İlk günden TestClient |
Merak edilenler
- FastAPI mı Flask mı? API servisi için FastAPI, HTML üreten küçük site için Flask. İkisi birbirinin rakibi değil, farklı işlerin aracıdır.
- Veritabanı nasıl bağlanır? İlk sürümde sözlük yeterlidir; kalıcılık gerektiğinde SQLAlchemy veya doğrudan
sqlite3modülü eklenir. Uç noktalar değişmez. - Kimlik doğrulama nasıl yapılır? JWT tabanlı token, başlıkta taşınır.
401ile403ayrımını doğru kurmak gerekir. - Async gerekli mi? Ağ bekleme yoğun işlerde evet; basit CRUD servislerinde senkron yazım fazlasıyla yeterlidir. Erken optimizasyon yapmayın.
- İstemci kodu nasıl üretilir?
/openapi.jsonşemasından otomatik üretim yapılır — doküman ve istemci aynı kaynaktan doğar. - Hız sınırı nasıl konur? 429 döndüren bir katman eklenir; sınırsız açık uç nokta, hem performans hem güvenlik riskidir.
Sonuç: sözleşme önce, kod sonra
Bir API'nin ömrü, altındaki teknolojiden çok sözleşmesine bağlıdır. URL'ler, metotlar, yanıt biçimleri ve hata kodları bir kez doğru kurulduğunda, veritabanı bileşeni, sunucu hattı ve hatta programlama dili bile değişebilir — istemciler farkı görmez.
Bugün yapacağınız tek şey: app.py dosyasına altı satırlık ilk servisi yazın, /docs'u açın ve bir isteği kendiniz deneyin. O sayfada gördüğünüz otomatik doküman, kodunuzun ne kadar düzenli olduğunun en dürüst aynasıdır.
Bu makale TechWave tarafından hazırlanmıştır.