REST API tasarımı: adlandırma, sayfalama, hata yanıtları ve sürümleme

İyi tasarlanmış bir API, dokümantasyona bakmadan bile tahmin edilebilir olur. Aşağıdaki kurallar evrensel değil, ama yaygın olarak kabul gören ve sonradan pişman olmayacağın tercihlerdir.

Kaynak odaklı adlandırma

URL'ler isim (kaynak), HTTP metodu fiil olsun:

Kaçın: /getUrunler, /urun/sil?id=42, /urunleriGuncelle.

• Çoğul isimler kullan (/urunler), tutarlı ol.
• URL'lerde küçük harf ve tire (/siparis-kalemleri), JSON alanlarında tek bir stil (camelCase veya snake_case) seç ve her yerde onu kullan.
• Kaynak olmayan işlemler için (ör. "siparişi iptal et") alt kaynak kabul edilebilir: POST /siparisler/42/iptal.

Doğru durum kodları

En sık kullanılanlar:

• 200 OK, 201 Created (oluşturulan kaydın adresini Location başlığında ver), 204 No Content (silme sonrası)
• 400 geçersiz istek, 401 kimlik doğrulama yok, 403 yetki yok, 404 bulunamadı, 409 çakışma, 422 doğrulama hatası, 429 çok fazla istek
• 500 sunucu hatası

Her şeye 200 dönüp gövdede {"basarili": false} yazmak, istemcilerin ve izleme araçlarının işini zorlaştırır. Ayrıntılar için forumdaki HTTP durum kodları rehberine bakabilirsin.

Tutarlı hata gövdesi

Bütün hatalar aynı biçimde dönsün:

{
  "hata": {
    "kod": "dogrulama_hatasi",
    "mesaj": "Gönderilen bilgilerde hata var.",
    "alanlar": {
      "email": "Geçerli bir e-posta adresi gir."
    }
  }
}

Makinenin okuyacağı sabit bir kod, insanın okuyacağı bir mesaj. Standart bir biçim istersen HTTP API'leri için tanımlanmış "Problem Details" (RFC 9457) biçimine bakabilirsin. Üretim ortamında hata gövdesine yığın izi (stack trace) veya SQL sorgusu koyma.

Sayfalama

Liste uç noktaları her zaman sayfalı olsun, yoksa veri büyüdükçe API yavaşlar.

• Sayfa/ofset: GET /urunler?sayfa=3&adet=20. Basit, ama büyük tablolarda ilerleyen sayfalar yavaşlar ve araya kayıt eklenirse aynı kayıt iki sayfada görünebilir.
• İmleç (cursor): GET /urunler?sonra=eyJpZCI6MTIzfQ&adet=20. Son görülen kaydın kimliğine göre devam eder. Büyük ve sürekli değişen verilerde daha tutarlı ve hızlı.

Yanıtta bir sonraki sayfaya nasıl gidileceğini belirt:

{ "veri": [ ... ], "sonraki": "/urunler?sonra=eyJpZCI6MTQzfQ&adet=20" }

Sayfa boyutuna bir üst sınır koy (ör. en fazla 100).

Filtreleme ve sıralama

GET /urunler?kategori=klavye&min_fiyat=500&sirala=-olusturma

- öneki azalan sıra için yaygın bir kuraldır. Sıralanabilir ve filtrelenebilir alanları izin listesiyle sınırla; kullanıcıdan gelen alan adını doğrudan sorguya koymak hem güvenlik hem performans sorunu yaratır.

Sürümleme

API'yi kullanan istemciler varken alan adı değiştirmek veya bir alanı kaldırmak onları bozar.

• En yaygın yöntem URL'de sürüm: /v1/urunler.
• Geriye dönük uyumlu değişiklikler (yeni alan, yeni uç nokta) sürüm gerektirmez.
• Kırıcı değişiklikler için yeni sürüm aç ve eski sürümü bir süre birlikte çalıştır, kapatma tarihini önceden duyur.

Diğer iyi alışkanlıklar

• Tarih ve saat: ISO 8601 biçiminde ve saat dilimiyle (2026-11-10T14:30:00Z).
• Para: Kayan noktalı sayı yerine kuruş cinsinden tam sayı veya ondalık metin.
• İdempotent oluşturma: Ödeme gibi kritik POST isteklerinde istemcinin gönderdiği bir Idempotency-Key başlığıyla aynı isteğin iki kez işlenmesini engelle.
• Hız sınırı: 429 döndür ve Retry-After başlığıyla ne zaman tekrar denenebileceğini belirt.
• Dokümantasyon: OpenAPI gibi bir şemayla belgelemek, hem dokümantasyonu hem de istemci kodu üretmeyi kolaylaştırır.