API Sürümleme (API Versioning) Nedir?
API sürümleme (API versioning), bir API’deki değişikliklerin numaralı ya da tarihli sürümlerle yayımlanmasıdır; eski sürümü kullanan entegrasyon bozulmadan çalışmayı sürdürür ve yeni sürüme planlı geçer.
Diğer Adları: API Versioning
API Sürümleme Nasıl Çalışır?
Sağlayıcı, bir alanın adını değiştirmek ya da bir alanı kaldırmak gibi geriye uyumsuz değişiklikleri yeni bir sürümde yayımlar; entegrasyon isteğinde hangi sürümü kullandığını belirtir. Shopify sürümleri yıl ve ay biçiminde adlandırır (2026-04 gibi), her üç ayda bir yeni sürüm yayımlar ve her kararlı sürümü en az 12 ay destekler; art arda gelen sürümler en az dokuz ay birlikte desteklenir.
Sürümler türe de ayrılır: canlı kullanım için önerilen kararlı sürüm, aynı gün yayımlanan ve geriye uyumsuz değişiklik içerebilen sürüm adayı (release candidate) ve haber verilmeden değişebilen, yalnızca erken deneme için kullanılan kararsız sürüm.
Kullanımdan Kaldırılan API ve Geçiş Takvimi
Kullanımdan kaldırma (deprecation), bir alanın, uç noktanın ya da özelliğin ileride kaldırılacağının duyurulmasıdır; özellik bir süre çalışır, sonra sonraki bir sürümde kaldırılır. Shopify bu duyuruları geliştirici değişiklik günlüğünde, API başvuru sayfalarında ve geliştirici panelindeki uyarılarla yapar. Desteği bitmiş bir sürümle yapılan istek reddedilmez; en eski erişilebilir kararlı sürümle yanıtlanır.
Bu davranış görünmez bir risk taşır: entegrasyon eski sürümü istemeye devam ederken yanıt yeni sürümün yapısıyla gelir ve kaldırılmış bir alana bağlı kod sessizce hata verebilir. Yanıttaki X-Shopify-API-Version başlığı, isteğin hangi sürümle yanıtlandığını gösterir.
API Sürümleme Mağaza Entegrasyonunu Nasıl Etkiler?
Pazaryeri, ERP ve kargo entegrasyonları sipariş, stok ve fiyat alanlarını belirli bir API sürümüne göre okur. Sağlayıcı bir alanı kaldırdığında ya da adını değiştirdiğinde, geçiş yapılmamış entegrasyon stok aktarımını durdurabilir ya da siparişleri eksik alanla kaydedebilir.
Örnek: Bir altyapı, sipariş yanıtındaki kargo alanının adını yeni sürümde değiştireceğini önceden duyurur. Mağazanın entegratörü değişikliği önce test ortamında yeni sürümle dener, sipariş ve stok aktarımını doğrular, sonra canlı entegrasyonu yeni sürüme taşır. Duyuruyu kaçıran entegrasyonda ise eski sürümün desteği bittiğinde kargo bilgisi boş gelmeye başlar.
API Sürümleme Hakkında Sık Sorulan Sorular
API sürümü ne zaman güncellenmeli?
Sağlayıcının destek takvimine göre planlanır. Kullanılan sürümün desteği bitmeden yeni sürüm test ortamında denenir ve geçiş yapılır.
Kullanımdan kaldırılan bir API hemen çalışmayı bırakır mı?
Genellikle bırakmaz; duyurudan sonra bir süre çalışır ve sonraki bir sürümde kaldırılır. Süre sağlayıcıya göre değiştiği için duyurudaki tarih esas alınır.