--- title: "API Sürümlemesi: Kırıcı Değişikliği Müşteriyi Kırmadan Yayınlamak" url: "https://cilginyazilim.com/blog/api-surumlemesi-kirici-degisikligi-nasil-yayinlarsiniz" description: "URL ve başlık bazlı API sürümleme yaklaşımlarının karşılaştırması; kırıcı değişiklikleri kademeli yayınlama ve kullanımdan kaldırma politikası." published: "2026-11-05T10:00:00+03:00" modified: "2026-11-05T10:00:04+03:00" author: "Çılgın Yazılım" category: "Kurumsal Yazılım ve Entegrasyon" tags: ["entegrasyon", "webhook", "semantic versioning", "API sürümleme", "rest api", "geriye uyumluluk", "kullanımdan kaldırma", "api tasarımı", "dokümantasyon", "istemci uyumluluğu", "mikroservis", "sözleşme testi", "yayın stratejisi"] site: "Çılgın Yazılım" language: "tr" --- # API Sürümlemesi: Kırıcı Değişikliği Müşteriyi Kırmadan Yayınlamak Bir alanı yeniden adlandırmak, entegre olmuş 40 istemciyi kırabilir. Sürümleme stratejisi ve kademeli geçiş planı. **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. ![API kırıcı değişiklik yayın adımları](https://cilginyazilim.com/uploads/blog/2026/07/api-surumlemesi-kirici-degisikligi-nasil-yayinlarsiniz-ozet.png) *Kaldırma işlemi son adımdır; ölçüm olmadan yapılan kaldırma tahmindir.* ## 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](https://cilginyazilim.com/blog/rest-api-tasarimi-iyi-bir-api-nasil-olur) 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](https://cilginyazilim.com/blog/ci-cd-nedir-kucuk-ekipler-icin-otomatik-dagitim) 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](https://cilginyazilim.com/blog/webhook-uclari-tasarlarken-5-yaygin-hata) bakın. Kullanımdan kaldırma başlıklarının standart tanımı için [MDN HTTP başlıkları referansı](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) 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ü?](https://cilginyazilim.com/blog/veri-senkronizasyonu-tek-yon-mu-cift-yon-mu) ## Sıkça Sorulan Sorular ### Küçük bir API için bu iş gereksiz mi? Dışarıya açık ve sizin kontrolünüzde olmayan istemciler varsa gereklidir. Yalnızca kendi ön yüzünüzün kullandığı bir API'de ise sürümleme yerine ön yüz ve arka ucu birlikte yayınlamak yeterlidir. ### v1 ve v2'yi aynı kod tabanında nasıl yönetmeliyim? En sürdürülebilir yol, hatta özgü olanı yalnızca sunum katmanında (dönüştürücüler/serileştiriciler) tutmak, iş mantığını tek bir yerde paylaşmaktır. İş mantığını kopyalamak iki sürümün zamanla farklı davranmasına yol açar. ### Kullanımdan kaldırma için ne kadar süre tanımalıyım? Kurumsal entegrasyonlarda 6-12 ay yaygındır; iç ekipler için birkaç hafta yeterli olabilir. Belirleyici olan sürenin uzunluğundan çok, tarihin baştan ilan edilmiş ve değişmemiş olmasıdır. ### İstemcilerin hangi alanları kullandığını nasıl ölçerim? Yanıt oluşturulurken hangi alanların talep edildiğini (örneğin alan seçimi destekliyorsa) veya istemcinin gönderdiği sürüm/başlık bilgisini istek başına kaydedin. Alan bazlı ölçüm mümkün değilse en azından uç ve istemci kırılımında kullanım sayacı tutun. --- Kaynak: [API Sürümlemesi: Kırıcı Değişikliği Müşteriyi Kırmadan Yayınlamak](https://cilginyazilim.com/blog/api-surumlemesi-kirici-degisikligi-nasil-yayinlarsiniz)