API versioning: kurumsal sistemlerde kimsenin açık konuşmadığı kısım

API versioning, kurumsal mimarilerde neredeyse herkesin fikir sahibi olduğu ama çok az ekibin gerçekten yönettiği bir konudur. Toplantılarda hızla kabul edilir, dokümantasyonlara eklenir ve çoğu zaman “ileride hallederiz” varsayımıyla hayata geçirilir.

Sorun şu ki API versioning kararları, etkisini hemen değil, aylar sonra, genellikle de beklenmeyen bir anda gösterir.

Ve o noktada geri dönüş maliyeti çok yüksektir.

Versioning teknik bir detay değildir

Teoride versioning, API tasarımının bir parçasıdır. Pratikte ise bu, organizasyonun verdiği uzun vadeli bir sözdür.

Bir API’ye yeni bir versiyon eklediğinizde, teknik olarak sadece bir endpoint açmazsınız. Aynı zamanda şunları da kabul etmiş olursunuz:

Eski versiyonun ne kadar süre yaşayacağını
Hangi ekiplerin onu desteklemeye devam edeceğini
Ne zaman ve hangi koşullarda kapatılacağını

Bu sorulara baştan cevap verilmediyse, versioning bir çözüm değil, ertelenmiş bir problemdir.

Sahada en sık karşılaşılan senaryo

Birçok kurumda API portföyü zamanla şu hale gelir:

v1 hâlâ aktif
v2 kısmen kullanılıyor
v3 roadmap’te
Hiçbiri tam olarak kapatılamıyor

Bu durum genellikle “disiplin eksikliği” olarak yorumlanır. Oysa gerçek neden daha derindedir:

Client’ların güncellenememesi
Harici partner bağımlılıkları
Versioning ile backward compatibility’nin karıştırılması

Sonuçta API sayısı artar, ama kontrol artmaz.

Asıl soru: Yeni versiyon mu, davranış yönetimi mi?

Üretimde çalışan sistemlerde versioning kararının merkezinde şu soru olmalıdır:

Bu değişiklik gerçekten yeni bir versiyon mu gerektiriyor, yoksa mevcut davranışı kontrollü şekilde evrimleştirmek mi istiyoruz?

Örneğin:

Yeni bir alan eklemek
Opsiyonel bir header desteklemek
Response formatını genişletmek

Bu değişikliklerin çoğu, doğru yönetildiğinde yeni bir versiyon gerektirmez. Ancak bu ayrımı net yapamayan ekipler, her değişikliği v+1 ile çözmeye çalışır.

Bu da kısa sürede yönetilemez bir API yüzeyi oluşturur.

Yöntem tartışması yanıltıcıdır

API versioning konuşulurken tartışma genellikle şu eksende döner:

URL mi?
Header mı?
Content negotiation mı?

Bu sorular teknik olarak önemlidir, ancak üretimde belirleyici olan bu değildir. Asıl belirleyici olan şudur:

Seçilen yöntem, organizasyonun operasyonel gerçekleriyle uyumlu mu?

Sahada gözlenen genel tablo şudur:

Dış dünyaya açık API’lerde URL tabanlı versioning daha öngörülebilirdir
Internal servislerde header tabanlı yaklaşımlar esneklik sağlar
Content negotiation güçlüdür ama operasyonel maliyeti yüksektir

Burada “doğru” yöntem yoktur. Yanlış bağlamda kullanılan doğru yöntem vardır.

Versioning’in görünmeyen bedeli: kapatma

Versioning kararlarının gerçek maliyeti, yeni versiyon açıldığında değil, eski versiyonu kapatmaya çalıştığınızda ortaya çıkar.

O noktada şu sorular gündeme gelir:

Bu versiyonu hâlâ kim kullanıyor?
Gerçekten kullanılmayan endpoint var mı?
Kapatırsak hangi iş süreçleri etkilenir?

Bu sorulara net cevap verilemiyorsa, eski versiyonlar hiçbir zaman kapanmaz. Sistem “geriye dönük uyumlu” kalmaz; donmuş hale gelir.

Üretimde işe yarayan yaklaşım

Başarılı ekipler, versioning’e bir numaralandırma problemi olarak değil, davranış yönetimi olarak yaklaşır.

Sahada çalışan örneklerde ortak noktalar şunlardır:

Aktif versiyon sayısı bilinçli olarak sınırlıdır
Yeni versiyon açılmadan önce kapatma planı bellidir
Gateway ve gözlemlenebilirlik katmanı aktif kullanılır
Client davranışı ölçülür, varsayılmaz

Bu yaklaşım, API’lerin kontrolsüz büyümesini engeller.

Karar vericiler için net çıkarımlar

Versioning masaya geldiğinde şu sorular net şekilde sorulmalıdır:

Bu versiyon ne zaman kapatılacak?
Kapatma kararını kim verecek?
Client’lar geçmezse ne olacak?
Gerçek kullanım verisini görebiliyor muyuz?

Bu sorular cevapsızsa, versioning teknik ilerleme değil, risk üretir.

Sonuç

API versioning bir tasarım tercihi değil, sözleşme yönetimidir.

İyi yönetildiğinde:

Değişimi güvenli kılar
Geriye dönük uyumu korur

Kötü yönetildiğinde ise:

API portföyünü şişirir
Operasyonel karmaşa yaratır

Ve çoğu zaman sorun, seçilen yöntem değil, hiç konuşulmayan sonuçlardır.

Sıkça sorulan sorular

API versioning stratejileri nelerdir?

Başlıca API versioning stratejileri: URI versioning (/v1/users), header versioning (Accept: application/vnd.api.v1+json), query parameter versioning (?version=1) ve content negotiation’dır. Her birinin avantajları ve dezavantajları vardır. URI versioning en yaygın ve anlaşılır olandır. Header versioning URL temizliğini korur ancak test ve debug’ı zorlaştırır.

URI versioning mi, header versioning mi tercih edilmeli?

Seçim kullanım senaryosuna bağlıdır. URI versioning (/v1/, /v2/) daha görünür, cache-friendly ve debug’ı kolaydır — çoğu enterprise API’de bu yöntem tercih edilir. Header versioning ise RESTful puristlere daha uygun olup URL yapısını temiz tutar, ancak API gateway konfigürasyonunu karmaşıklaştırabilir. Pragmatik yaklaşım: Public API’lerde URI, internal API’lerde header versioning kullanılabilir.

Eski API versiyonları ne zaman kullanımdan kaldırılmalıdır?

API deprecation stratejisi şu faktörlere bağlıdır: aktif consumer sayısı, SLA taahhütleri ve migrasyon karmaşıklığı. Tipik yaklaşım şöyledir: Yeni versiyon yayınlandıktan sonra en az 6–12 aylık bir sunset period verilir, deprecation header’ları (Sunset, Deprecation) eklenir, consumer’lara proaktif bildirim yapılır ve kullanım metrikleri izlenerek sıfıra yaklaştığında versiyon kaldırılır. Enterprise ortamlarda 12–24 aylık süreler daha yaygındır.

Breaking change’ler nasıl yönetilir?

Zorunlu alan ekleme, alan silme veya tip değişikliği gibi breaking change’ler yeni bir major versiyon gerektirir. Additive change’ler (yeni opsiyonel alan, yeni endpoint) minor versiyon veya mevcut versiyon içinde yapılabilir. API design review süreci ile breaking change’ler erken tespit edilmeli, consumer impact analizi yapılmalı ve migration guide hazırlanmalıdır. Contract testing ile geriye uyumluluk otomatik olarak doğrulanmalıdır.