API Sürümlemesi: Kırıcı Değişikliği Müşteriyi Kırmadan Yayınlamak

API sürümleme, dışarıya açtığınız her uçla birlikte imzaladığınız sessiz bir sözleşmenin yönetimidir. Kendi uygulamanızın içinde bir alan adını değiştirmek beş dakikalık iştir; aynı alanı yüzlerce istemcinin entegre olduğu bir API'de değiştirmek, ilan edilmiş bir kesinti anlamına gelebilir. Bu yazıda hangi değişikliğin gerçekten kırıcı olduğunu, sürümleme stratejilerinin gerçek maliyetlerini ve kırıcı bir değişikliği kimseyi kırmadan yayınlamanın adımlarını ele alıyoruz.

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

Ekiplerin çoğu bu ayrımı sezgiyle yapar ve yanılır. Net bir liste yardımcı olur.

Kırıcı olanlar: Bir alanı kaldırmak veya yeniden adlandırmak; bir alanın tipini değiştirmek (metin iken sayı yapmak); zorunlu bir istek parametresi eklemek; bir alanın anlamını değiştirmek (tutarı kuruştan liraya çevirmek); hata durum kodlarını değiştirmek; varsayılan sıralamayı değiştirmek.

Kırıcı olmayanlar: Yanıta yeni bir alan eklemek; isteğe bağlı yeni bir parametre eklemek; yeni bir uç eklemek; performans iyileştirmesi yapmak.

Buradaki kritik ayrıntı şudur: yeni alan eklemek, ancak istemciler bilmedikleri alanları görmezden geliyorsa kırıcı değildir. Katı şema doğrulaması yapan bir istemci, beklemediği bir alan geldiğinde hata verebilir. Bu yüzden API dokümantasyonunuzda "yeni alanlar eklenebilir, istemciler bilinmeyen alanları yok saymalıdır" şeklinde açık bir uyumluluk taahhüdü bulunmalıdır. Uç tasarımının genel ilkeleri için REST API tasarımı yazımıza bakabilirsiniz.

Yaklaşımlar ve gerçek maliyetleri

URL'de numara: /api/v1/, /api/v2/

En yaygın ve en anlaşılır yöntem. Avantajı görünürlüğüdür: tarayıcıda test edilebilir, log'larda okunabilir, önbellek anahtarı doğal olarak ayrışır. Dezavantajı, numaranın kaynak adresine karışmasıdır — kavramsal olarak aynı kaynak iki farklı adreste yaşar. Buna rağmen pratikte en az sürtünme üreten seçenektir ve çoğu ekip için doğru varsayılandır.

Başlıkta numara: Accept veya özel başlık

Adresler temiz kalır, seçim içerik pazarlığıyla yönetilir. Teorik olarak daha doğrudur; pratikte hata ayıklamayı zorlaştırır, ara katmanların önbellekleme davranışını karmaşıklaştırır ve istemcilerin başlığı unutmasıyla sessizce yanlış uca düşülmesine yol açar.

Hiç numaralamamak: sadece toplayıcı değişiklikler

Bazı büyük sağlayıcılar hiç ana numara çıkarmaz; yalnızca geriye uyumlu değişiklik yapar ve kırıcı değişikliği asla yayınlamaz. Bu, disiplin gerektiren ama istemciler için en konforlu yaklaşımdır. Uzun vadede API yüzeyinizde biriken ölü alanları kabullenmeniz gerekir.

Kırıcı bir değişikliği yayınlamanın beş adımı

Diyelim ki musteri_adi alanını ad ve soyad olarak ayırmanız gerekiyor. Doğru sıra şudur:

1. Genişlet. Yeni alanları ekleyin, eskisini de doldurmaya devam edin. Bu aşamada hiçbir istemci etkilenmez; yeni istemciler yeni alanları kullanmaya başlayabilir.
2. İşaretle. Dokümantasyonda ve yanıt başlığında eski alanın kullanımdan kaldırılacağını, hangi tarihte kalkacağını belirtin. Deprecation ve Sunset başlıkları bunun için standartlaşmıştır.
3. Ölç. Hangi API anahtarının hangi alanı hâlâ okuduğunu bilmiyorsanız, kaldırma kararınız tahmindir. İstek başına kullanılan alanları telemetriye yazmak, bu adımın tek güvenilir yoludur.
4. Haber ver. Kalan istemcilere kitlesel duyuru değil, doğrudan iletişim gerekir. Genellikle geriye kalan birkaç entegrasyon, sizin haberdar olmadığınız kritik iş akışlarıdır.
5. Kaldır. Kullanım sıfıra indikten sonra kaldırın. Kaldırmadan önce kısa süreli bir "karartma testi" (alanı birkaç saatliğine boş döndürmek) sürprizleri erken ortaya çıkarır.

Eski uçları sonsuza kadar yaşatmamak

Bu yaklaşımın gizli maliyeti, her aktif hattın ayrı bakım, ayrı test ve ayrı güvenlik yaması gerektirmesidir. İki ana hattı aynı anda desteklemek yönetilebilir; dördü genellikle değildir. Bu yüzden yeni bir hat açarken destek süresini de ilan edin: "her ana hat, ardılı yayınlandıktan sonra 12 ay desteklenir" gibi bir politika, hem istemcilere planlama imkânı verir hem de sizi sonsuz bakımdan kurtarır.

Hatlar arası uyumu otomatik korumanın en etkili yolu sözleşme testleridir: eski uçların yanıt şemasını doğrulayan testler, sürekli entegrasyonda çalıştığında kırıcı bir değişiklik yanlışlıkla yayına çıkamaz. Bu testleri dağıtım hattına bağlamak için CI/CD yazımız pratik bir başlangıç sunar.

Webhook'lar: unutulan taraf

Sürümleme tartışılırken genellikle yalnızca istemcinin size gönderdiği istekler düşünülür. Oysa sizin istemciye gönderdiğiniz webhook yükleri de bir sözleşmedir ve orada yapılan bir değişiklik, karşı taraftaki ayrıştırıcıyı sessizce bozar. Webhook yüklerini de sürümlemek ve abonelik kaydında sürüm tutmak gerekir; bu alandaki yaygın hatalar için webhook tasarımı yazımıza bakın.

Kullanımdan kaldırma başlıklarının standart tanımı için MDN HTTP başlıkları referansı iyi bir kaynaktır.

Sonuç

API sürümleme, teknik bir numaralandırma meselesi değil, bir iletişim disiplinidir. Doğru strateji genellikle en görünür olanıdır — URL'de numara — ama asıl belirleyici olan biçim değil, kırıcı değişikliği yayınlarken izlediğiniz sıradır: önce genişlet, sonra işaretle, sonra ölç, sonra haber ver, en son kaldır. Bu sıralamayı atlayan her ekip er ya da geç aynı cümleyi duyar: "Sizin dünkü güncellemeniz bizim entegrasyonu bozdu." Bugün API'nizde kaç istemcinin hangi alanı kullandığını ölçebiliyor musunuz? Cevap hayırsa, stratejinizden önce telemetriye ihtiyacınız var demektir.

İlgili Yazılar

• Veri Senkronizasyonu: Tek Yön mü, Çift Yön mü?