REST API Tasarım İlkeleri ve En İyi Uygulamalar

REST (Representational State Transfer), web servisleri oluşturmak için en yaygın kullanılan mimari stildir. İyi tasarlanmış bir REST API, geliştiricilerin kolayca anlayıp entegre edebileceği, ölçeklenebilir ve bakımı kolay bir arayüz sunar. Bu rehberde, profesyonel REST API tasarımının temel ilkelerini ve en iyi uygulamalarını ele alacağız.

REST Temel İlkeleri

REST mimarisi altı temel ilkeye dayanır:

• İstemci-Sunucu Ayrımı: İstemci ve sunucu birbirinden bağımsız geliştirilir
• Durumsuzluk (Stateless): Her istek, işlenmesi için gereken tüm bilgiyi içermelidir
• Önbelleklenebilirlik: Yanıtlar açıkça önbelleklenebilir veya önbelleklenemez olarak işaretlenmelidir
• Katmanlı Sistem: İstemci, doğrudan sunucuya mı yoksa bir ara katmana mı bağlandığını bilmek zorunda değildir
• Tek Tip Arayüz: Kaynaklar tutarlı ve öngörülebilir bir arayüzle sunulmalıdır
• İsteğe Bağlı Kod: Sunucu, istemciye çalıştırılabilir kod gönderebilir (opsiyonel)

HTTP Metodları

REST API'lerde her işlem için uygun HTTP metodunu kullanmak kritik öneme sahiptir:

GET    /api/users          → Tüm kullanıcıları listele
GET    /api/users/42        → 42 ID'li kullanıcıyı getir
POST   /api/users           → Yeni kullanıcı oluştur
PUT    /api/users/42        → 42 ID'li kullanıcıyı tamamen güncelle
PATCH  /api/users/42        → 42 ID'li kullanıcıyı kısmen güncelle
DELETE /api/users/42        → 42 ID'li kullanıcıyı sil

Önemli kurallar:

• GET asla veri değiştirmemelidir (idempotent ve güvenli)
• PUT idempotent olmalıdır — aynı isteği iki kez göndermek aynı sonucu vermelidir
• POST idempotent değildir — her çağrı yeni bir kaynak oluşturabilir
• DELETE idempotent olmalıdır — silinmiş bir kaynağı tekrar silmek hata değil, 204 dönmelidir

URL Yapısı

İyi bir URL tasarımı, API'nizin kullanılabilirliğini büyük ölçüde artırır:

✅ Doğru:
GET /api/v1/users
GET /api/v1/users/42/orders
GET /api/v1/products?category=electronics

❌ Yanlış:
GET /api/v1/getUsers
GET /api/v1/user/42/getOrders
POST /api/v1/deleteUser/42

URL tasarım kuralları:

• Kaynak adları çoğul isim olmalıdır: /users, /products
• Fiil kullanmayın — HTTP metodu zaten eylemi belirtir
• Küçük harf ve tire kullanın: /order-items
• İlişkili kaynaklar için iç içe yapı kullanın: /users/42/orders
• Filtreleme, sıralama ve sayfalama için query parametreleri kullanın

HTTP Durum Kodları

Doğru durum kodu kullanmak, API'nizin anlaşılabilirliği için kritiktir:

// Başarılı yanıtlar
200 OK              → Genel başarı
201 Created         → Kaynak oluşturuldu (POST sonrası)
204 No Content      → Başarılı ama döndürülecek veri yok (DELETE sonrası)

// İstemci hataları
400 Bad Request     → Geçersiz istek
401 Unauthorized    → Kimlik doğrulanmadı
403 Forbidden       → Yetki yok
404 Not Found       → Kaynak bulunamadı
409 Conflict        → Çakışma (ör. zaten var olan email)
422 Unprocessable   → Doğrulama hatası
429 Too Many Req.   → Rate limit aşıldı

// Sunucu hataları
500 Internal Error  → Sunucu hatası
503 Unavailable     → Servis geçici olarak kullanılamıyor

Versiyonlama

API'niz değiştikçe mevcut istemcilerin çalışmaya devam etmesi gerekir. Yaygın versiyonlama yöntemleri:

// URL versiyonlama (en yaygın)
GET /api/v1/users
GET /api/v2/users

// Header versiyonlama
Accept: application/vnd.myapp.v2+json

// Query parametresi
GET /api/users?version=2

Sayfalama (Pagination)

Büyük veri setleri için sayfalama zorunludur:

GET /api/users?page=2&limit=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

Hata Yönetimi

Tutarlı ve bilgilendirici hata yanıtları, geliştirici deneyimini iyileştirir:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Doğrulama hatası oluştu",
    "details": [
      {
        "field": "email",
        "message": "Geçerli bir email adresi giriniz"
      }
    ]
  }
}

Kimlik Doğrulama

Modern API'lerde en yaygın kimlik doğrulama yöntemleri:

• Bearer Token (JWT): Authorization: Bearer eyJhbGci...
• API Key: X-API-Key: abc123 veya query parametresi olarak
• OAuth 2.0: Üçüncü parti entegrasyonlar için standart protokol