Çağıranlar için API versiyonlama en iyi uygulamaları

API versiyonlama, onu değiştirdikten sonra eski bir sözleşmeyi çalışır tutma pratiğidir, böylece çağıranlar sizin değil kendi programlarına göre ilerleyebilir. O cümle önemli olan iki kararı içerir: sözleşmeyi değiştirmenin ne sayıldığı, ve eskisinin ne kadar süre çalışmaya devam ettiği. Versiyon numarasının nerede yaşadığı, ki çoğu versiyonlama tartışması bununla ilgilidir, üçünün en az önemlisidir ve doğru yapılması en kolay olanıdır.

Bir API ne zaman versiyonlanmalı?

Bir API’yi sadece bir değişiklik doğru bir çağıranı bozacaksa versiyonlayın. Ekleme değişiklikleri, yeni alanlar, yeni endpoint’ler, yeni isteğe bağlı parametreler, bir versiyona ihtiyaç duymaz; eski sözleşmeye yazılmış çağıranlar çalışmaya devam eder ve yeni yetenek basitçe oradadır. Bir breaking change buna ihtiyaç duyar, çünkü alternatif bir çağıranın bunu bir hatadan öğrenmesidir. Ekleme olanlar dahil her sürümü versiyonlamak, çağıranlara versiyonların gürültü olduğunu öğretir, ve önemli bildirimleri okumayı bırakırlar.

Pratik test, breaking change makalesindekiyle aynıdır: sadece dokümante edilmiş davranışa güvenen bir çağıran çalışmaya devam etmek için bir şeyi değiştirmek zorundaysa, değişiklik bir versiyona ihtiyaç duyar. Değilse, mevcut versiyon altında gönderin ve bir changelog girdisi yazın.

Hangi API versiyonlama şeması kullanılmalı?

Çağıranlarınızın en kolay görüp ayarlayabileceği şemayı kullanın, ki bu çoğu genel API için URL yolunda bir versiyon veya tarihli bir versiyon başlığıdır. Dört yaygın şema, yetenekten çok çağırandan ne istediklerinde farklılık gösterir, ve seçim için doğru temel budur.

URL yolu en görünür ve en az esnek olanıdır. Her çağıran bir log satırı okuyarak hangi versiyonda olduğunu görebilir, ve bir versiyon sıçraması bul-değiştir’dir. Maliyeti: tüm yüzey birden hareket eder, hepsi için yeni bir versiyon basmadan tek bir endpoint’in sözleşmesini değiştiremezsiniz, bu yüzden yol versiyonları nadir ve büyük olma eğilimindedir.

Versiyon başlığı, URL’leri stabil tutar ve hiçbir şey göndermeyen çağıranlar için sunucunun bir varsayılan seçmesine izin verir, GitHub’ın REST API versiyonlaması şöyle çalışır: X-GitHub-Api-Version içinde tarihle adlandırılmış bir versiyon, versiyonsuz çağıranların bozulmaması için varsayılan olarak en eski desteklenen versiyonla. Maliyeti: versiyon bir URL’de görünmezdir ve yeni bir istemcide unutulması kolaydır.

Tarihli hesap versiyonu, bir ekleme yapılmış başlık şemasıdır: versiyon hesaba karşı saklanır, böylece her istek hiçbir şey göndermeden onu alır. Stripe’ın API versiyonlaması her hesabı oluşturulduğu versiyona sabitler ve bir isteğin bunu Stripe-Version ile geçersiz kılmasına izin verir. Bu, çağıran için en dostça şemadır ve çalıştırması en çok iş gerektirendir, çünkü sunucu her desteklenen versiyon ile şu anki arasında çeviri yapmak zorundadır.

Sorgu parametresi ve medya türü, her ikisi de çalışır ve ikisi de görünürlük testini farklı şekillerde başarısız olur: bir sorgu parametresi bir URL oluştururken kolayca düşer, ve bir medya türü versiyonu, bir çağıranın hata ayıklamak için kullandığı hemen hemen her araç için görünmezdir. Stripe’ın tarih tabanlı şeması tarih yaklaşımının en bilinen örneğidir ve Stripe API’sini nasıl versiyonluyor onu adım adım anlatır.

API versiyonlama pratikte nasıl yapılır?

Pratikte bir versiyon, adlandırılmış bir davranış kümesidir, ve sunucu her isteği bunlardan birine eşler. Adımlar, ismi hangi şema taşırsa taşısın aynıdır.

1. Versiyonları semantik versiyona değil, tarihe veya tam sayıya göre adlandırın. Bir web API’si bir paket değildir. Çağıranlar bir URL’nin minor versiyonunu sabitleyemez, bu yüzden v2 veya 2026-08-26 bir çağıranın ihtiyaç duyduğu her şeyi söyler, ve semantik versiyonlama şemanın yerine getiremeyeceği bir uyumluluk sözü ima eder.
2. Versiyonu umursamayan kod yollarının dışında tutun. Bir versiyon, iş mantığını dallandırmak yerine kenarda bir çeviri katmanı seçmelidir. Kod tabanının iki tam kopyası, bir versiyonun nasıl bakımsız kaldığıdır.
3. Her versiyona bir varsayılan ve bir doküman verin. Versiyon göndermeyen çağıranlar, sabitlenmemiş bir istemcinin sürüm günü bozulmaması için en yeniyi değil en eski desteklenen olanı alır. Her versiyonun öncekinden ne değiştiğini söyleyen bir sayfası vardır.
4. Bir destek penceresi belirleyin ve yayımlayın. Google’ın versiyonlama kılavuzu AIP-185, makul ve iyi duyurulmuş bir geçiş süresi ister ve beta işlevselliği için bile 180 gün önerir. Bir pencere seçin, yazın, ve versiyon başına yeniden müzakere etmeden uygulayın.
5. Versiyonları endpoint’leri emekliye ayırdığınız gibi emekliye ayırın. Penceresini geçmiş bir versiyon, herhangi bir deprecate edilmiş API ile aynı muameleyi görür: bir duyuru, her yanıtta bir Sunset başlığı (RFC 8594), kalan çağıranlara yarı yolda bir hatırlatma, ve tutan bir kaldırma tarihi.

Bir REST API’sinde v1 ve v2 nedir?

v1 ve v2, aynı sunucunun aynı anda desteklediği iki sözleşme için isimlerdir. Bir v2, v1’deki bir şey çağıranlarını bozmadan değiştirilemediği için vardır, bu yüzden değişiklik yeni bir sözleşmeye gitti ve eskisi çalışmaya devam etti. Numaralar v2nin tamamlandığını veya v1’in öldüğünü ima etmez; ikisi de sadece dokümantasyon öyle söylüyorsa doğrudur. Her çeyrekte görünen bir v3, ekleme değişikliklerin versiyonlandığının, veya sözleşmenin hiçbir zaman değişikliği emmek için tasarlanmadığının bir işaretidir. gRPC aynı sorunu farklı bir şekilde çözer: gRPC ve Protobuf API değişiklikleri versiyonlamayı bir URL yolu yerine bir .proto dosyasındaki paket adı üzerinden ele alır, ve bir alanı yeniden adlandırmanın ücretsiz ama yeniden numaralandırmanın hiçbir REST çağıranının riskli olarak tanımayacağı bir breaking change olduğu bir wire formatını.

Bir versiyon değişikliği ne duyurmalı?

Bir versiyon değişikliği, neyin bozulduğunu, kimi etkilediğini, nasıl göç edileceğini, ve önceki versiyonun ne kadar süre çalışmaya devam ettiğini duyurmalıdır. Girdi, herhangi bir başka breaking change girdisiyle aynı şekle sahiptir, artı destek penceresini belirten bir satır. İşte başlıkla versiyonlanan bir API için bir tane:

API versiyon 2026-11-01 mevcuttur. Versiyon 2025-06-15, 1 Kasım 2027’ye kadar destekleniyor. 2026-11-01’de yeni: GET /invoices, amount’ı ondalık string yerine en küçük birimlerde tam sayı olarak döndürüyor, ve deprecate edilmiş customer_name alanı customer nesnesi lehine kaldırılıyor. 2025-06-15’te amount’ı string olarak parse eden çağıranları etkiler, ki bu Haziran 2025’ten önce oluşturulmuş sabitlenmemiş istemciler için varsayılandır. Göç: amount’ı tam sayı olarak parse edin ve ismi customer.name’den okuyun. Hazır olduğunuzda X-Api-Version: 2026-11-01’i sabitleyin. Versiyon sabitlemeyen çağıranlar için hiçbir şey değişmiyor.

Son cümle, çoğu okuyucunun okumayı bırakmasına izin veren cümledir, ve her versiyon duyurusuna aittir. Changelog örnekleri sayfası böyle versiyonlayan API’lerden girdiler içerir, ve iyi olanlar ile geri kalanı arasındaki fark çoğunlukla o son cümledir.

Bir versiyon değiştiğinde kime bildirilir?

Eski versiyondaki herkese, bireysel olarak, ve diğer herkes için changelog’a. Bir versiyon değişikliği, “bunun hakkında paylaşım yaptık”ın kesinlikle önemli olan çağıranları kaçırdığı tek durumdur: iki yıl önce bir versiyon sabitleyip o zamandan beri bir sürüm notu okumamış olanlar. Kullanım verisi kim olduklarına cevap verir; bildirim onlara kodlarının olduğu yerde, yanıt başlıklarında ve hesap sahibine bir mesajda ulaşmalıdır.

Çalıştırdığımız döngüde, bir versiyonu duyuran girdi, onu gönderen pull request’ten hazırlanır, bir insan tarafından incelenir, ve versiyonlu bir istemcinin JSON olarak okuyabileceği feed ve widget’e yayımlanır. Widget geri bildirimi değişikliği isteyen veya çözdüğü hatayı bildiren ve pull request’in kapattığı bir GitHub issue’suna dönüşen herkes, girdi yayına girdiğinde o issue’da bilgilendirilir. Mekanizma herhangi bir girdiyle aynıdır; bir versiyon sıçraması sadece en yüksek riski olan girdidir.

FAQ

Her API değişikliği yeni bir versiyon almalı mı? Hayır. Sadece breaking change’ler. Ekleme değişiklikleri, bir changelog girdisiyle mevcut versiyon altında gönderilir. Ekleme değişikliklerini versiyonlamak, çağıranları versiyonları görmezden gelmeye eğitir.

URL versiyonlama mı yoksa başlık versiyonlaması mı daha iyi? URL versiyonlaması, çağıranlar için görmesi daha kolaydır ve sizin için parça parça geliştirmesi daha zordur; başlık versiyonlaması bunun tersidir. Çok sayıda küçük istemcisi olan genel bir API için, URL versiyonlaması daha az başarısız olur. Çeviri katmanı olan büyük bir API için, tarihli başlık versiyonu daha iyi ölçeklenir.

Aynı anda kaç versiyon desteklenmeli? Destek pencerenizin izin verdiği kadar az, ve asla sınırsız bir sayı değil. İki veya üç eşzamanlı versiyon normaldir; bundan fazlası genellikle versiyonların emekliye ayrılmadığı anlamına gelir.

Versiyonsuz istekler ne almalı? En eski desteklenen versiyon, böylece mevcut sabitlenmemiş istemciler çalışmaya devam eder, hangi versiyonu aldıklarını onlara söyleyen bir yanıt başlığıyla.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Geliştirici dokümantasyonu, Changelog örnekleri