REST API Tasarımı: En İyi Pratikler ve Sık Yapılan Hatalar

İyi Bir API Neden Bu Kadar Önemli?

Bir uygulamanın kalitesi çoğu zaman arka planda çalışan API'ının kalitesiyle doğru orantılıdır. Kötü tasarlanmış bir API; entegrasyon hatalarına, güvenlik açıklarına ve gelecekte değiştirilmesi neredeyse imkânsız olan teknik borçlara yol açar. İyi tasarlanmış bir REST API ise yıllarca sorunsuz hizmet verir.

REST'in Temel İlkeleri

• Stateless (Durumsuz): Her istek kendi içinde tüm bilgiyi taşımalıdır. Sunucu, istemci hakkında oturum bilgisi tutmaz.
• Uniform Interface (Tekdüze Arayüz): Kaynaklara erişim için standart HTTP metodları kullanılır.
• Client-Server Ayrımı: İstemci ve sunucu bağımsız gelişebilir.
• Cacheable (Önbelleklenebilir): Yanıtlar uygun durumlarda önbelleklenebilir olmalıdır.

URL Tasarımı — Doğru ve Yanlış

# ❌ Kötü URL tasarımı örnekleri
GET  /getUsers
POST /createNewUser
GET  /deleteUser?id=5
POST /user/doLogin

# ✅ İyi URL tasarımı (isim tabanlı, eylem tabanlı değil)
GET    /api/v1/users          # Tüm kullanıcıları listele
POST   /api/v1/users          # Yeni kullanıcı oluştur
GET    /api/v1/users/5        # ID'si 5 olan kullanıcıyı getir
PUT    /api/v1/users/5        # ID'si 5 olan kullanıcıyı güncelle
DELETE /api/v1/users/5        # ID'si 5 olan kullanıcıyı sil
GET    /api/v1/users/5/posts  # Kullanıcının gönderilerini listele

HTTP Durum Kodlarını Doğru Kullanın

Kod	Anlam	Ne Zaman Kullanılır?
200 OK	Başarılı	GET, PUT başarıyla tamamlandığında
201 Created	Oluşturuldu	POST ile yeni kaynak oluşturulduğunda
204 No Content	İçerik yok	DELETE başarılı olduğunda
400 Bad Request	Hatalı istek	İstemci hatalı veri gönderdiğinde
401 Unauthorized	Kimlik doğrulama gerekli	Token eksik veya geçersizse
403 Forbidden	Erişim yasak	Yetki yetersizse (giriş yapılmış ama izin yok)
404 Not Found	Bulunamadı	Kaynak mevcut değilse
500 Server Error	Sunucu hatası	Beklenmeyen sunucu taraflı hata

Tutarlı Hata Yanıtları Döndürün

// ❌ Kötü: Tutarsız ve bilgisiz hata yanıtı
{ "error": true }

// ✅ İyi: Standart ve açıklayıcı hata yanıtı
{
  "success": false,
  "status": 422,
  "message": "Doğrulama başarısız",
  "errors": [
    { "field": "email", "message": "Geçerli bir e-posta adresi giriniz" },
    { "field": "password", "message": "Şifre en az 8 karakter olmalıdır" }
  ],
  "timestamp": "2026-09-11T14:00:00Z"
}

Versiyonlama (Versioning)

API'nızda kırılgan (breaking) değişiklikler yaptığınızda eski istemcileri bozmamak için versiyonlama şarttır:

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

# Header tabanlı versiyonlama
Accept: application/vnd.codemarefi.v2+json