API sürümleme rehberi: kırıcı değişiklikleri yönetmek ve eski sürümleri emekli etmek

API versiyonlama neden gerekir?

Bir API yayımlandığında onu kullanan istemciler (mobil uygulamalar, iş ortağı sistemleri, iç servisler) belli bir sözleşmeye güvenerek yazılır. API sahibi alan adını değiştirir, bir alanı kaldırır ya da yanıt yapısını yeniden düzenlerse istemci bozulabilir. Versiyonlama, API'nin değişirken bu istemcilerle sözleşmeyi korumasının yoludur.

Sorun, API sahibinin tüm istemcileri kontrol edemediği durumlarda büyür. İç servislerde ekipler koordine olabilir; dış geliştiriciler ya da iş ortakları ise kendi takvimleriyle çalışır. Eski bir mobil uygulama sürümü aylarca kullanımda kalabilir. Bu yüzden değişiklikler istemcilere zarar vermeden, öngörülebilir biçimde sunulmalıdır.

Versiyonlama tek başına yeterli değildir. Asıl hedef, kırıcı değişikliği olabildiğince azaltmak ve kaçınılmaz olduğunda yönetilen bir geçiş yürütmektir.

Kırıcı değişiklik nedir, nasıl tespit edilir?

Kırıcı değişiklik (breaking change), mevcut istemcinin değişiklik öncesinde çalışan davranışını bozan değişikliktir. Her değişiklik kırıcı değildir; ayrım yapabilmek versiyonlama kararının temelidir.

Genellikle kırıcı sayılanlar: • Bir uç noktayı ya da alanı kaldırmak veya adını değiştirmek. • Bir alanın veri tipini değiştirmek (metinden sayıya gibi). • Zorunlu yeni bir istek parametresi eklemek. • Yanıt kodlarının veya hata biçiminin anlamını değiştirmek. • İşin sırasını ya da yan etkisini değiştirmek (örneğin bir isteğin artık ek bir işlem tetiklemesi).

Genellikle kırıcı olmayanlar: yanıta yeni isteğe bağlı alan eklemek, yeni uç nokta eklemek, isteğe bağlı parametre eklemek. Ancak bu da istemcinin bilinmeyen alanlara nasıl tepki verdiğine bağlıdır; katı biçimde doğrulayan bir istemci yeni alanda hata verebilir.

Tespit için API şeması (örneğin OpenAPI tanımı) sürümler arasında karşılaştırılır; sözleşme testleri ve otomatik fark araçları kırıcı değişikliği yayımdan önce yakalar. İstemcilerin gerçekten hangi alanları kullandığını izleme verisinden görmek, riski doğru değerlendirmeyi sağlar.

Versiyonlama stratejileri nelerdir?

Sürüm bilgisini taşımanın birkaç yaygın yolu vardır.

Yol (URI) versiyonlama: sürüm adresin içinde yer alır. Anlaşılır ve önbelleğe dostudur, herkesin kolayca gördüğü bir yöntemdir. Dezavantajı, adresin kaynağı değil sürümü de tanımlaması ve her sürümün ayrı bir adres seti haline gelmesidir.

Başlık (header) versiyonlama: sürüm özel bir istek başlığıyla ya da içerik türü pazarlığıyla belirtilir. Adresleri temiz tutar, ama tarayıcıdan denemek ve hata ayıklamak daha zordur.

Sorgu parametresiyle versiyonlama: sürüm sorgu dizisinde taşınır. Basittir, ancak önbellek ve yönlendirme açısından dikkat ister.

Sürümsüz evrim: API kırıcı değişiklik yapmadan, yalnızca eklemelerle genişler. Eski alan korunur, yeni alan eklenir. Bu yaklaşım en çok istemci güveni sağlar, fakat zamanla API'nin eski yüklerini taşımasına yol açar.

Seçim kararı, istemci sayısına, ekibin sürüm destekleme kapasitesine ve API'nin açık ya da kapalı olmasına göre verilir. Önemli olan, seçilen stratejinin belgelenmesi ve tüm ekiplerce tutarlı uygulanmasıdır.

Geriye uyumluluk pratikte nasıl korunur?

Geriye uyumluluğun temel ilkesi, istemcilere verilen sözü bozmamaktır. Bunu sağlayan pratikler: • Ekleyerek genişletmek: var olanı değiştirmek yerine yeni alan ve yeni uç nokta eklemek. • Toleranslı okuma: hem sunucu hem istemci bilinmeyen alanları yok sayar. • Varsayılan değer: yeni isteğe bağlı parametreler eski davranışı koruyan varsayılanla gelir. • Eski alanı hemen silmek yerine kullanımdan kaldırma (deprecation) işaretlemek. • Sözleşme testi: istemcilerin beklediği yapı otomatik testlerle her yayında doğrulanır.

Bir örnek: yanıtta tam ad tek alanda dönüyor ve bunu ad ile soyad olarak ayırmak istiyorsunuz. Güvenli yol, yeni ad ve soyad alanlarını eklemek, eski tam ad alanını bir süre aynı şekilde döndürmek ve kullanım izlemeyle eski alanın kimler tarafından okunduğunu görmektir. Eski alan ancak kullanıcılar taşındıktan sonra kaldırılır.

Sık yapılan hata, iç tüketicileri küçümsemektir. İç servislerin de aynı sözleşme disiplinine ihtiyacı vardır; çünkü iç bir kırılma da üretim kesintisine yol açar.

Geçiş, kullanımdan kaldırma ve emeklilik nasıl yürütülür?

Yeni bir sürüm yayımlandıktan sonra eski sürümün kaderi açık yönetilmelidir. Süreç genellikle şu aşamalardan geçer: yeni sürümün duyurulması, eski sürümün kullanımdan kaldırıldığının ilan edilmesi, geçiş rehberinin yayımlanması, eski sürüm kullanıcılarının izlenip bilgilendirilmesi ve belirlenen tarihte eski sürümün kapatılması.

Bilgilendirme çok kanallı yapılır: geliştirici portalındaki duyuru, e-posta, değişiklik günlüğü ve mümkünse yanıt başlıkları ya da uyarı mesajları. Takvim, istemcilerin gerçekçi şekilde geçiş yapabileceği bir süre tanımalıdır; mobil uygulamalar gibi güncellenmesi yavaş istemcilerde bu süre uzar.

Kapatma öncesinde eski sürümü hâlâ çağıran istemciler tespit edilir ve birebir iletişime geçilir. Takvim bir kez ilan edildiğinde sürekli ertelenmemelidir; aksi halde ekipler geçişi önemsemez. Ama kritik bir iş ortağı hazır değilse bilinçli bir istisna kararı da yönetilebilir olmalıdır.

Yönetişim: sürümleme kararlarını kim verir?

Versiyonlama bir teknik meseleden çok bir yönetişim meselesidir. Hangi değişikliğin kırıcı sayılacağı, hangi onay süreçlerinden geçeceği, kaç sürümün aynı anda desteklendiği ve emeklilik koşulları belge haline getirilmelidir.

İyi çalışan bir yönetişim şu unsurları içerir: yazılı API tasarım kuralları, değişiklik önerisi ve inceleme süreci, otomatik şema karşılaştırması içeren yayın hattı, değişiklik günlüğü, geliştirici iletişimi için sorumlu kişi ve sürüm destek politikası. Politika, ürün ekibi ile mühendisliğin birlikte belirlediği bir ticari karardır; çünkü eski sürümü desteklemek maliyetlidir.

Sık hatalar: • Her küçük değişiklik için yeni sürüm açmak; sürüm sayısı yönetilemez hale gelir. • Hiç sürüm açmayıp kırıcı değişiklikleri sessizce yayımlamak. • Sürümler arası farkları belgelememek.

Bu becerinin Mindset programlarındaki yeri

Mindset kataloğundaki API Versiyonlama ve Geriye Uyumluluk Stratejileri eğitiminin modülleri Kırıcı Değişiklik Analizi, Versiyonlama Stratejileri ile Geçiş, Emeklilik ve Yönetişim başlıklarından oluşur. API Tasarımı ve Yönetimi eğitiminde de Versiyonlama ve Evrim modülü ile API Tasarım Prensipleri, OpenAPI ve API Dokümantasyonu gibi ilişkili başlıklar yer alır.