API Sürümü Değişince Entegrasyon Bozulur mu? Geçiş Planı

Sağlayıcı API sürümünü yükselttiğinde entegrasyonunuz bozulabilir; ama bozulma sürpriz değildir, çünkü kıran değişiklik türleri sayılıdır ve iki sürümü bir süre birlikte çalıştırarak geçiş kesintisiz yapılır. Asıl sebep sürümün değişmesi değil, kendi tarafınızın tek bir yanıt biçimine sıkı sıkıya bağlı yazılmış olmasıdır.

Aşağıda sürümün hangi biçimlerde değiştiği, hangi değişikliğin kırıp hangisinin kırmadığı, kendi kodunuzu nasıl dayanıklı yazacağınız ve geçişin adım sırası var. Buradaki akış hem pazaryeri ve kargo gibi dış servisler hem de kendi yazılımınızın başka bir sisteme açtığı uç için aynıdır.

Sürüm değişikliği hangi biçimlerde gelir

Her sağlayıcı sürümü aynı yerden söylemez. Hangi biçimle karşı karşıya olduğunuzu bilmek, geçişi nasıl yöneteceğinizi de belirler.

• Adreste sürüm: uç adresinin içinde sürüm geçer. Yeni sürüm yeni bir adres demektir, eskisi bir süre daha açık kalır. Yönetmesi en kolay biçimdir.
• Başlıkta sürüm: istek başlığında sürüm numarası ya da bir tarih gönderilir. Başlığı göndermeyi unutan istek sağlayıcının o anki varsayılan sürümüne düşer; varsayılan değiştiği gün sizin kodunuz da değişmiş olur.
• Hesapta sürüm: sağlayıcının panelinde hesabın bağlı olduğu sürüm seçilir. Riski şudur: paneli başka biri açıp değiştirince kodda hiçbir şey değişmeden davranış değişir.
• Duyurulmamış değişiklik: sürüm numarası aynı kalır, yanıtın içeriği değişir. Alan eklenir, bir alan artık boş gelmeye başlar, hata metni başka yazılır. En çok zaman kaybettiren biçim budur, çünkü aramaya nereden başlayacağınız belli değildir.

Hangi değişiklik kırar, hangisi kırmaz

Fark listesini okurken her satırı "bu bizi kırar mı" diye işaretlemek, geçişin yarısını halleder. Genel çerçeve şöyledir:

Limit tarafı için ayrı bir yazı var: istek sınırı ve yeniden deneme düzeni. Mükerrer kayıt riski de aynı şekilde tekillik anahtarıyla kapatılır.

Kendi tarafınızı dayanıklı yazmak

Sürüm geçişlerini acısız yapan yazılımların ortak özellikleri var. Bunlar geçiş günü değil, entegrasyon ilk yazılırken kurulur.

• Bilmediğiniz alanı yok sayın. Yanıtta fazladan alan görünce hata üretmeyin.
• Bilinmeyen durum değerini "tanımsız" kovasına alın ve kaydı düşürmeyin; insan bakana kadar bekletin.
• Tutar ve tarihi geldiği gibi saklayıp kendi tipinize ayrı bir adımda çevirin. Böylece tip değişikliği tek yerde karşılanır.
• Alan sırasına ve listedeki eleman sayısına güvenmeyin; alanı adıyla okuyun.
• Gelen ham yanıtı bir süre saklayın. Sürüm değiştiğinde eski kaydı yeniden işlemenin tek yolu budur.
• Dış servisin modelini kendi modelinize çeviren tek bir eşleyici katman olsun. Yanıt alanı kırk ayrı ekranda okunuyorsa her sürüm değişikliği kırk ayrı düzeltme demektir.
• Sözleşme testi yazın: beklediğiniz alanların var olduğunu ve tipinin değişmediğini her gün otomatik kontrol eden küçük bir test, sessiz değişikliği siz fark etmeden yakalar.

Geçiş planı: adım sırası

1. Sağlayıcının duyuru kanalını tek bir kişiye bağlayın. Duyuru genelde panel bildirimi ya da teknik bülten olarak gelir; kimsenin okumadığı bir adrese düşüyorsa yoktur.
2. Fark listesini kendi alanlarınıza indirin. Sağlayıcının yüz maddelik listesinin belki altısı sizi ilgilendirir.
3. Yeni sürümü önce test ortamında çalıştırın, canlı veriyle değil.
4. Eşleyiciyi iki sürümü de anlayacak hâle getirin ve hangi sürümün kullanılacağını bir ayarla seçin. Geri dönmek böylece kod değişikliği değil, ayar değişikliği olur.
5. Küçük bir trafikle canlıda deneyin: tek bir mağaza, tek bir şube ya da günün belli bir saati.
6. Kuyrukta eski biçimle bekleyen kayıtları boşaltın. Geçiş anında kuyruk doluysa o kayıtlar iki biçim arasında sıkışır.
7. Geri dönüş yolunu yazılı tutun; devreye alma ve geri dönüş planı burada da geçerlidir.
8. Eski sürümü kendi tarafınızdan kapatın. Açık bırakılan eski yol, aylar sonra kimsenin hatırlamadığı bir arıza olarak geri gelir.

Duyurulmamış değişikliği fark etmek

Sürüm numarası değişmeden davranış değiştiğinde kimse size haber vermez. Fark etmenin yolu, entegrasyonun kendi sağlık sayılarını ölçmektir: beklenen alanın boş geldiği kayıt oranı, ayrıştırma hatası sayısı, tanımsız duruma düşen kayıt sayısı ve günlük adet mutabakatı. Bu sayılardan biri bir günde sıçradıysa sebep çoğu zaman sizin son yayınınız değil, karşı taraftır.

Ölçümü kurmak için canlıda hata izleme ve alarm düzeni yeterlidir; ayrı bir araç gerekmez. Önemli olan, sayının bir insana ulaşan bir eşiği olmasıdır.

Kısa kontrol listesi

• Hangi sürümü kullandığınız yazılı mı, ayarla mı seçiliyor?
• Duyuruları okuyan belirli bir kişi var mı?
• Fark listesi kendi alanlarınıza indirgenmiş mi?
• İki sürümü birlikte çalıştırabiliyor musunuz?
• Bilinmeyen alan ve bilinmeyen durum kaydı düşürüyor mu?
• Ham yanıt saklanıyor mu, geçmiş kayıt yeniden işlenebilir mi?
• Boş alan ve ayrıştırma hatası oranı ölçülüyor mu?

KAV Yazılım, ERP, pazaryeri, kargo ve ödeme entegrasyonlarını bu sürüm dayanıklılığıyla kurar; mevcut bir entegrasyonun sürüm geçişini de aynı adımlarla planlar.