API Tasarımı: Sürümleme ve Geriye Dönük Uyumluluk

Bir API yayına alındığı andan itibaren sözleşme haline gelir. Karşı tarafta kodu yazan geliştirici, alan adlarının ve yanıt biçiminin sabit kalacağını varsayar. Bu varsayım bozulduğunda hata kendi tarafında değil istemcide çıkar ve çoğu zaman geç fark edilir.

Sürdürülebilir API tasarımının özü şudur: geliştirmeye devam ederken mevcut istemcilerin çalışmaya devam etmesini sağlamak.

Hangi değişiklikler kırıcıdır?

Ayrım pratikte nettir. Var olan bir şeyi kaldırmak, adını değiştirmek ya da anlamını değiştirmek kırıcıdır. Yeni bir şey eklemek genellikle kırıcı değildir.

• Kırıcı: alan kaldırmak, alan adını değiştirmek, veri tipini değiştirmek, zorunlu yeni parametre eklemek, hata kodunun anlamını değiştirmek.
• Kırıcı değil: yanıta yeni alan eklemek, isteğe bağlı parametre eklemek, yeni uç nokta açmak, sıralamayı belgelenmiş sınırlar içinde iyileştirmek.

Yanıta yeni alan eklemenin kırıcı sayılmaması, istemcinin bilmediği alanları yok saymasına bağlıdır. Bu beklenti belgelerde açıkça belirtilmelidir.

Sürümleme yöntemleri

Üç yaygın yaklaşım vardır. Adres yolunda sürüm taşımak en görünür ve en kolay hata ayıklanabilir olanıdır; tarayıcıdan ve günlük kayıtlarından doğrudan okunur:

GET /api/v1/kullanicilar
GET /api/v2/kullanicilar

// başlık ile
GET /api/kullanicilar
Accept: application/vnd.uygulama.v2+json

Başlık tabanlı sürümleme adresleri sabit tutar, ancak testi ve önbelleklemeyi zorlaştırır. Sorgu parametresiyle sürümleme ise en kolay uygulanan yöntemdir fakat istemcilerin sürüm belirtmeyi unutması riskini taşır. Küçük ve orta ölçekli projelerde yol tabanlı sürümleme genellikle en pratik seçimdir.

Sürüm sayısını sınırlı tutmak

Her sürüm ayrı bakım yükü demektir. İkiden fazla etkin sürüm taşımak, aynı hatanın birden fazla yerde düzeltilmesi anlamına gelir. Pratik kural, en fazla iki sürümü etkin tutmak ve yeni sürüm çıktığında en eskisi için kaldırma takvimi ilan etmektir.

Sürüm artırmak son çaredir. Bir değişiklik geriye dönük uyumlu biçimde yapılabiliyorsa yeni sürüm açılmaz. Örneğin kaldırılacak alan hemen silinmek yerine bir süre yanıtta bırakılır.

Sözleşmeyi belgeyle sabitlemek

Sürümleme kararlarının işe yaraması için sözleşmenin yazılı olması gerekir. Makine tarafından okunabilir bir tanım dosyası hem belgeyi hem istemci kodunu hem de testleri aynı kaynaktan üretmeyi mümkün kılar.

Tanım dosyası sürüm kontrolünde tutulduğunda, kırıcı değişiklik fark gözden geçirmesinde doğrudan görünür hale gelir. Alan silindiğinde ya da tipi değiştiğinde bu değişiklik incelemede gözden kaçmaz.

Sözleşme testleri de aynı amaca hizmet eder. İstemcinin beklediği yanıt yapısını doğrulayan testler sunucu tarafında çalıştırıldığında, uyumsuzluk yayına çıkmadan yakalanır.

Kullanımdan kaldırma süreci

Kaldırma işlemi duyurulmadan yapılmaz. Süreç genellikle üç adımdır: belgede işaretleme, yanıt başlığıyla uyarı ve takvim sonunda kaldırma. Standart başlıklar bu bildirimi otomatik izlenebilir hale getirir:

Deprecation: true
Sunset: Sat, 31 Oct 2026 23:59:59 GMT
Link: <https://ornek.com/api/v2>; rel="successor-version"

Kaldırma tarihinden önce eski uca gelen isteklerin kaydı tutulmalıdır. Trafik sıfıra inmediyse tarih ertelenir; hangi istemcinin hâlâ eski sürümü kullandığı bu kayıtlardan görülür.

Hata biçimini tutarlı tutmak

Yanıt gövdesi kadar hata biçimi de sözleşmenin parçasıdır. Aynı API içinde farklı uçların farklı hata yapısı döndürmesi, istemci tarafında her uç için ayrı çözümleme kodu yazılmasına yol açar:

{
  "hata": {
    "kod": "gecersiz_parametre",
    "mesaj": "limit değeri 1 ile 100 arasında olmalı",
    "alan": "limit"
  }
}

Hata kodları metin olarak tanımlandığında istemci bunlara göre dallanabilir. Yalnızca HTTP durum koduna dayanan tasarım, aynı durumun farklı nedenlerini ayırt etmeyi imkansız kılar.

Kontrol listesi

• Kırıcı değişiklik yalnızca yeni sürümde yapılır.
• Etkin sürüm sayısı ikiyi geçmez.
• Kaldırma öncesinde duyuru ve takvim yayımlanır.
• Eski sürüm trafiği ölçülmeden kapatılmaz.
• Hata biçimi tüm uçlarda aynıdır.
• İstemcilerin bilinmeyen alanları yok sayması belgelenir.

İlgili yazılar

• Monolit mi Mikroservis mi? Karar Kriterleri
• PHP'de SQL Injection: PDO ile Güvenli Sorgu Yazımı