API'iniz bir kez yayına girdiğinde artık yalnızca size ait değildir. Dün gece mağazaya giren mobil uygulama, sabah trafiğinde hâlâ eski bir çağrı biçimini kullanıyor. Bu yüzden her kırıcı değişiklik, aslında iki tarafın da imzaladığı bir sözün tek taraflı değişmesidir. Versiyonlama bu sözü resmileştirmenin yoludur; ama nereye yazılacağı hakkında üç rakip ekol var: URL'de, başlıkta ve hiçbir yerde.

URL'de Sürüm: Görünür ve Kaba

En yaygın yöntem, sürümü yolun içine koymaktır. Yönlendirme katmanı, önbellek ve erişim günlükleri sürümü doğal olarak görür; hangi sürümün ne kadar kullanıldığı tek bir gruplamayla çıkar. Belgelendirme de kolaylaşır, çünkü her sürümün kendi sayfası ve kendi örnekleri olur.

// Sürümlü yönlendirme: eski istemciler v1'de kalır, yeniler v2'ye alınır
router.get('/v1/siparisler', v1SiparisleriListele);
router.get('/v2/siparisler', v2SiparisleriListele);

Bedeli ise görünürlükle birlikte gelir: adresler şişer, istemci tarafında adres değiştirme zorunluluğu doğar ve iki sürümü yan yana yaşatmak, kod tabanında sessizce çoğalan kopya dallar demektir. Bir sürümü emekli etmek, basit bir dosya silme değil, koordinasyon gerektiren bir proje hâline gelir.

Başlıkta Sürüm: Sessiz ve Zarif

İkinci yaklaşım sürümü içerik müzakeresine gömer. Adres sabit kalır, sürüm isteğin kabul başlığında taşınır. Yer imleri ve entegrasyonlar bozulmaz, yeni sürüm eskiyle aynı kaynakta yaşayabilir ve REST'in özgün tasarımına daha sadıktır.

GET /siparisler HTTP/1.1
Accept: application/vnd.tekno.v2+json

Zarif olduğu kadar görünmezdir. Destek ekibi "hangi sürümü kullanıyorsunuz" diye sorduğunda cevap bir günlük satırında gizlidir; hata ayıklarken ve kabuk komutlarıyla test ederken başlığı elle taşımak yoran bir disiplin ister. Önbellek katmanınız istek gövdesine göre ayrıştırma yapmıyorsa, iki sürümün yanıtları yanlış yerde buluşabilir.

Bu yöntemin bir de kültürel bedeli vardır: sürüm görünür olmadığı için teknik olmayan paydaşlar onu fark etmez. "Yeni sürüm ne zaman çıkıyor" sorusu toplantı masasında cevapsız kalır, çünkü sürüm artık bir adres değil, bir müzakere başlığıdır. Bunu telafi etmek için sürüm bilgisini yanıt başlıklarına yazıp her hata kaydında sormanız gerekir.

Hiç Sürüm Çıkarmamak: Sözleşmeyi Genişlet

Üçüncü seçenek bir sürüm politikası değil, disindir: kırıcı değişiklik yapmamak. Yeni alan eklerken mevcut olanların anlamını değiştirmezsiniz; kaldıracağınız alanı önce kullanımdan düşürür, istemcilerin göçünü bekler, sonra silersiniz. Dahili servislerde ve küçük ekiplerde bu çoğu zaman yeterlidir ve en ucuz yoldur: sürüm çifti, iki kat belge ve geçiş dönemi diye bir şey oluşmaz.

Bu yolun bedeli öngörülebilirlik değil, sıkı bir kod inceleme kültürüdür. Tek bir "gelişigüzel yeniden adlandırma" birimi, sözleşmeyi sessizce kırar ve hiçbir sürüm numarası olmayacağı için suç bulmak zorlaşır.

Bu yüzden sürümsüz API'lerde şemayı sözleşme gibi işleyin: istek ve cevap alanlarını bir şema doğrulayıcıya bağlayın, kırıcı değişikliği otomatik testlerle yakalayın. Şema değişikliği olmadan onaylanan bir kod incelemesi, sözleşmeyi kimse okumadan imzalamaktır; sorumluluk da incelemeyi onaylayanın omuzlarında kalır. Ayrıca istemcilerin tanımadıkları alanları yok saymasını alışkanlık hâline getirin: hiç kullanılmayan bir alanı bir gün eklemek, kırıcı değişiklik sayılmamalıdır.

Doğru cevap tek bir strateji değil, ölçektir. Kamuya açık bir API için URL sürümü ve net bir geçiş takvimi; büyük ekiplerin iç platformlarında başlık tabanlı müzakere; küçük ve disiplinli ekipler için ise sürümsüz, ekleyici bir sözleşme çoğu zaman en dengeli seçimdir. Sürüm çıkarmak bir zafer değil, kabulleniştir: sözü bir daha değiştiremeyeceğinizi kabul etmektir. Hangi yolu seçerseniz seçin, kararı yazıya dökün: sürüm politikası diye bir sayfanız yoksa, politikanız her krizde yeniden icat edilir.