Python ile API Geliştirme: FastAPI ile REST Servis Yazma Rehberi — TechWave
Python

Python ile API Geliştirme: FastAPI ile REST Servis Yazma Rehberi

FastAPI ile REST servis yapısını gösteren TechWave çizimi

Görsel: TechWave tarafından hazırlandı.

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:

KuralNe demekİyi örnekKötü örnek
AdreslemeHer kaynak bir URI ile çağrılır/urunler/42/urunGetir?id=42
HTTP metoduEylem metotla taşınırDELETE /urunler/42POST /urunSil
DurumsuzlukHer istek kendine yeterToken başlıkta taşınırSunucuda oturum değişkeni
TemsilVeri JSON olarak taşınır{"ad":"Kitap"}HTML gövdesine gömülü veri
Stateless cacheYanıtlar önbelleklenebilirETag 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ı

ÖzellikFastAPIFlaskDjango REST Framework
OdakAPI servisleriMikro web + APIBüyük ölçekli uygulama
DoğrulamaPydantic, yerleşikElle veya eklentiSerializer ile
DokümantasyonOtomatik OpenAPIEklenti gerekirEklenti gerekir
PerformansÇok yüksek (async)OrtaOrta
Öğrenme eğrisiDüşük-ortaÇok düşükYü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.

FastAPI servis akışını gösteren TechWave çizimi

Uç nokta tasarımı: kaynak ve metot

Örnek senaryo: bir ürün kataloğu. Kaynaklar çoğul, eylemler metotlarla:

MetotUç noktaNe yaparBaşarı kodu
GET/urunlerListeyi döndürür (sayfalı)200
GET/urunler/42Tek kaydı döndürür200 / 404
POST/urunlerYeni kayıt oluşturur201
PUT/urunler/42Kaydı tamamen günceller200 / 404
DELETE/urunler/42Kaydı siler204 / 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.

Pydantic doğrulama akışını gösteren TechWave çizimi

Hata yönetimi: 422, 404 ve ötesi

KodAnlamıNe zaman döner
400Kötü istekSemantik olarak anlamsız veri
401Kimlik doğrulanmadıToken yok veya geçersiz
403Yetki yokGiriş yapılmış ama erişim yasak
404BulunamadıKayıt yok ya da URL yanlış
422Doğrulama hatasıPydantic modeli reddetti
429Çok fazla istekHız sınırı aşıldı
500Sunucu 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.

API test senaryolarını gösteren TechWave çizimi

Yayınlama akışı: geliştirmeden canlıya

  1. Yerel doğrulama: uvicorn app:app ile çalıştırın, /docs'tan deneyin
  2. Test: TestClient ile en az üç senaryo
  3. Ortam değişkenleri: anahtar, veritabanı adresi, port — kodda değil ortamda
  4. Sunucu: Uvicorn'u bir süreç yöneticisi (systemd, Docker) arkasına koyun
  5. Sınır: Dışa açmadan önce hız sınırı (429) ve kimlik doğrulama
  6. İ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

HataSonuçDoğrusu
URL'de eylem taşımakTahmin edilemez APIURL kaynak, metot eylem
Her şeyi 200 ile döndürmekİstemci tarafında karmaşaGerçek HTTP kodları
Doğrulamayı elle yapmakDağınık, tekrar eden kodPydantic modeli
Açık uç noktada yetki yokVeri sızıntısı401/403 kontrolü
Dokümanı elle güncellemekKodla uyumsuzlukOtomatik OpenAPI
Testi sona bırakmakKı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 sqlite3 modülü eklenir. Uç noktalar değişmez.
  • Kimlik doğrulama nasıl yapılır? JWT tabanlı token, başlıkta taşınır. 401 ile 403 ayrı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.