REST API Tasarımı: İyi Bir API Nasıl Kurgulanır?

REST API tasarımı, kod yazmadan önce verilen kararların toplamıdır. Bir API yayına çıktıktan sonra onu kullanan istemciler oluşur ve sözleşmeyi değiştirmek pahalı hâle gelir. Bu yüzden iyi API, "çalışan" API değil, tahmin edilebilir API’dir: kullanan geliştirici bir uç noktayı gördükten sonra diğerlerini tahmin edebiliyorsa tasarım başarılıdır.

1. Kaynak adlandırma: isimler, fiiller değil

Adres satırında yapılan işi değil, üzerinde çalışılan kaynağı belirtin. İşi HTTP metodu anlatır.

• GET /api/v1/orders — liste
• GET /api/v1/orders/42 — tek kayıt
• POST /api/v1/orders — oluşturma
• PUT /api/v1/orders/42 — tam güncelleme, PATCH — kısmi güncelleme
• DELETE /api/v1/orders/42 — silme

/getOrders, /orderDelete gibi adlandırmalar tutarsızlığın kapısını açar; ekipteki her geliştirici kendi fiilini uydurur. Çoğul isim kullanın ve istisnasız uygulayın.

2. Durum kodları: anlamına uygun kullanın

Her yanıtı 200 ile dönüp gövdede success: false yazmak, istemci tarafında hata yönetimini imkânsız hâle getirir. Asgari sözlük şudur:

• 200 başarılı, 201 oluşturuldu, 204 içerik yok (silme sonrası)
• 400 istek hatalı, 401 kimlik doğrulanmadı, 403 yetki yok, 404 kaynak yok
• 409 çakışma (aynı kayıt zaten var), 422 doğrulama hatası
• 429 hız sınırı aşıldı, 500 sunucu hatası

401 ile 403 farkı özellikle önemlidir: birincisi "kim olduğunu bilmiyorum", ikincisi "kim olduğunu biliyorum ama bu işlemi yapamazsın" demektir.

3. Hata biçimi tek olmalı

Tüm hataların aynı gövde yapısında dönmesi, istemci kodunu sadeleştirir. Örnek bir sözleşme:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Gönderilen veri doğrulanamadı.",
    "fields": { "email": "Geçerli bir e-posta giriniz." }
  }
}

Makine tarafından okunacak bir code, insana gösterilecek bir message ve alan bazlı ayrıntılar. Bu üçlü, arayüzün hatayı doğru yerde göstermesini sağlar.

4. Kimlik doğrulama ve yetki

Kimlik doğrulama "sen kimsin", yetkilendirme "bunu yapabilir misin" sorusudur. İkincisi çok daha sık atlanır. Kritik kural: kaydın kime ait olduğu her istekte sunucuda kontrol edilmelidir. Aksi hâlde kullanıcı adres satırındaki numarayı değiştirerek başkasının verisini okur; bu, IDOR olarak bilinen ve sahada en sık rastlanan açıktır.

Token’ların ömrü kısa tutulmalı, yenileme akışı ayrı bir uç noktayla yönetilmeli ve çıkışta jeton geçersiz kılınabilmelidir. Ayrıntılı kontrol listesi için OWASP REST güvenlik notları iyi bir başlangıçtır.

5. Filtreleme, sıralama, sayfalama

Liste uç noktaları büyümeye mahkûmdur. Baştan sınır koyun: varsayılan sayfa boyutu (örneğin 20), en yüksek sayfa boyutu (örneğin 100) ve sorgu parametreleriyle filtreleme.

GET /api/v1/orders?status=paid&created_from=2026-01-01&sort=-created_at&page=2&per_page=50

Yanıtın içine toplam kayıt sayısını ve sayfa bilgisini koyun; istemcinin kaç sayfa olduğunu tahmin etmesi gerekmesin.

6. Sürümleme ve geriye dönük uyum

Yayına çıkmış bir alanı silmek veya adını değiştirmek kırıcı değişikliktir. Yeni alan eklemek ise güvenlidir. Kırıcı değişiklik gerektiğinde yeni sürüm açın ve eskisi için kapanış tarihi duyurun. Mobil uygulamalarda kullanıcıların bir kısmı aylarca eski sürümde kalacağı için bu disiplin zorunludur.

7. Belgelendirme ve örnekler

API’yi kullanacak kişi, dokümana iki soruyla gelir: bu uç nokta ne döndürür ve hata durumunda ne olur? Her uç nokta için gerçek bir istek ve gerçek bir yanıt örneği koymak, sayfalarca açıklamadan daha etkilidir.

Belgeyi koddan üretmek en sürdürülebilir yoldur; elle yazılan dokümanlar üçüncü sürümde gerçeklikten kopar. Ayrıca test ortamı için örnek kimlik bilgileri sağlayın: entegrasyonu yapan geliştiricinin ilk beş dakikada başarılı bir istek atabilmesi, projenin genel süresini belirgin biçimde kısaltır.

8. Zaman aşımı, yeniden deneme ve idempotency

Ağ üzerinden yapılan her çağrı başarısız olabilir. İstemci isteği gönderip yanıt alamadığında ne yapacağını bilmelidir. Sorun şudur: istek sunucuya ulaşmış ama yanıt kaybolmuşsa, yeniden deneme aynı siparişi iki kez oluşturur.

Çözüm, oluşturma isteklerinde tekrar güvenli (idempotent) davranıştır. İstemci her isteğe benzersiz bir anahtar ekler; sunucu aynı anahtarla gelen ikinci isteği yeni kayıt olarak değil, ilk sonucun tekrarı olarak döner. Ödeme, sipariş ve stok hareketi gibi kritik uçlarda bu yaklaşım, çift kayıt sorunlarının tamamını ortadan kaldırır.

9. Hız sınırı ve kötüye kullanım koruması

Açık bir API, er ya da geç yanlış yazılmış bir istemci tarafından saniyede yüzlerce istekle dövülür. İstemci başına dakikalık sınır koyun, sınır aşıldığında 429 dönün ve Retry-After başlığıyla ne kadar bekleneceğini söyleyin.

Sonuç

İyi bir API tasarımı, kullanan geliştiricinin dokümana bakma ihtiyacını azaltır. Tutarlı adlandırma, doğru durum kodları, tek biçim hata gövdesi, her istekte yetki kontrolü ve baştan planlanmış sürümleme; bu beş karar, API’nizin üç yıl sonra hâlâ genişletilebilir olup olmayacağını belirler.