SÖZLÜKOtomasyon ve entegrasyon

API versiyonlama nedir?

Kısa tanım

API versiyonlama, bir API'de yapılan değişikliklerin, onu kullanan sistemleri bozmadan yayımlanabilmesi için API'nin sürümlerinin numaralandırılıp birlikte yönetilmesidir.

Son güncelleme:

API versiyonlama nedir, bir API değişince entegrasyonunuz neden bozulabilir?

Kargo firmasının API'sine bağlanan entegrasyonunuz, sağlayıcının o gün sunduğu alanlara ve biçime göre yazılmıştır. Sağlayıcı bir alanın adını değiştirirse entegrasyon bir sabah sessizce çalışmayı bırakabilir. API versiyonlama bu riski yönetir: değişiklikler yeni sürümle yayımlanır, eski sürüm bir süre çalışmaya devam eder. Stripe'ın sürümleme dokümanı bu yaklaşımı örnekler: ayrıntılar Stripe'ın API sürümleme sayfasında (yeni sekmede açılır) yer alır ve geriye dönük uyumsuz değişikliklerin büyük sürümlerle geldiğini anlatır.

API versiyonlama yöntemleri nelerdir?

API versiyonlama yöntemleri, sürümün isteğe nasıl iliştirildiğine göre ayrılır. Microsoft'un API tasarım rehberi de sürümlemenin bir web API için gerekli olduğunu ve farklı yaklaşımlarla yapılabildiğini anlatır. Yaygın üç yöntem vardır.

  • Adreste sürüm: istek adresinin içinde v1, v2 gibi bir bölüm.
  • Sorgu parametresi: adresin sonunda sürüm bilgisi.
  • Başlık: sürümün istek başlığında belirtilmesi.

API sürüm değişikliği nasıl yönetilir?

API sürüm değişikliği, hem sağlayıcı hem kullanıcı için planlı bir iştir. Sağlayıcı eski sürümün ne zaman kapanacağını önceden duyurur. Kullanıcı olarak sizin görevinizi, hangi sürümü kullandığınızı bilmek, duyuruları izlemek ve yeni sürüme geçişi test ortamında denemek oluşturur. Geçişi son güne bırakmayın.

Geriye dönük uyumluluk nedir?

Eski kullanıcıları bozmayan değişikliklere geriye dönük uyumlu denir. İsteğe bağlı yeni bir alan eklemek genellikle uyumludur. Mevcut bir alanın adını ya da türünü değiştirmek, bir adresi kaldırmak ya da zorunlu yeni alan eklemek ise uyumsuzdur ve yeni sürüm gerektirir. Kendi API'nizi sunuyorsanız bu ayrımı baştan netleştirin.

Sürüm geçişi nasıl test edilir?

Yeni sürüme geçmeden önce entegrasyonunuzun kritik işlemlerini deneme ortamında çalıştırın: sipariş oluşturma, stok güncelleme, durum sorgulama. Yanıtlardaki alan adlarını ve türlerini eski sürümle karşılaştırın. Farkları bir listeye alın ve her birinin entegrasyonunuzu nasıl etkilediğini değerlendirin. Geçişi canlıya küçük bir grupta alıp izlemek riski azaltır.

Eski sürüm ne kadar süre desteklenir?

Her sağlayıcı kendi destek süresini duyurur. Eski sürümün kapanış tarihini takvime yazın ve geçişi bu tarihten önce tamamlayın. Duyuruları kaçırmamak için sağlayıcının bildirim listesine abone olun ve bu e-postaların ulaştığı bir ortak adres kullanın.

Entegrasyonu güncel tutmak için ne yapılır?

Kullandığınız her API için sürüm bilgisini bir tabloda tutun. Sağlayıcının değişiklik duyurularına abone olun ve entegrasyonun hata günlüğünü izleyin; sürüm değişikliği çoğu zaman beklenmedik hatalarla kendini gösterir. Bağlantıları hazır ve güncel kurmak için Entegrasyon ve Otomasyon Marketi sayfasına bakabilirsiniz.

API versiyonlama nerede karşınıza çıkar?

  • API adresinde "v1" ya da "v2" gibi sürüm bölümünün bulunması
  • API sağlayıcısının eski sürümü belirli bir tarihte kapatacağını duyurması
  • Entegrasyonun belirli bir API sürümüne sabitlenmesi
  • Yeni alanın eski sürümü bozmadan eklenmesi

Entegrasyonlarınızı güncel tutun

Sağlayıcıların API değişikliklerini izleyen ve entegrasyonları güncel tutan hazır çözümler.

API versiyonlama hakkında sık sorulanlar

API versiyonlama neden gerekir?
API'yi kullanan sistemler yazıldıkları biçime güvenir. Değişiklik bunları bozabilir. Sürümleme, eski kullanıcıların eski davranışı korumasını, yenilerin yeni davranışa geçmesini sağlar.
Hangi değişiklikler API'yi bozar?
Alan adının ya da türünün değişmesi, zorunlu yeni bir alan eklenmesi, bir adresin kaldırılması gibi geriye dönük uyumsuz değişiklikler bozar. Yeni isteğe bağlı alan eklemek genellikle bozmaz.
Sürüm nasıl belirtilir?
Yaygın yollar adreste sürüm numarası, sorgu parametresi ya da istek başlığıdır. Hangisinin kullanılacağı API sağlayıcısının dokümanında belirtilir.
ÜCRETSİZ, 1 İŞ GÜNÜ

İlk adımı birlikte atalım

Operasyonunuzdaki elle yürüyen işleri inceleyip ayda kaç saatin sistemle yürüyebileceğini yazılı olarak veriyoruz; teknik bilgi ve taahhüt gerekmez.

  • Kredi kartı yok
  • 1 iş gününde dönüş
  • KVKK uyumlu
  • Veriler şifreli bağlantıyla iletilir