API sürüm değişiklikleri ve kırılan entegrasyonları önleme

Pazartesi sabahı pazarlama sorumlusu haftalık özete bakıyor: web sitesindeki formdan gelen kayıt sayısı sıfır değil, sadece düşük. Tatil dönemi diye geçiştiriliyor. On bir gün sonra bir müşteri adayı e-posta yazıyor: formu doldurdum, kimse dönmedi. Kayıtlara bakılıyor, kayıt orada duruyor. Entegrasyon çalışıyor, hata günlüğü tertemiz, bağlantı yeşil görünüyor. Tek sorun, form aracının bir sürüm güncellemesinde telefon alanının adını değiştirmiş olması. Kayıtlar telefonsuz açılmış, telefon şartına bağlı otomatik atama kuralı da hiçbirini kimseye atamamış. On bir günlük talep kimsenin masasına düşmeden havuzda beklemiş.

Kırılan entegrasyonların çoğu böyle görünür: hata vermeden, sessizce ve haftalar sonra fark edilerek. Aşağıda entegrasyonların neden sessizce kırıldığını, sağlayıcıların sürümü nasıl işaretlediğini, kırılma türlerinin ne kadar sürede fark edildiğini, entegrasyon envanterinin nasıl çıkarıldığını, duyuruların neden yanlış kişiye gittiğini, test ve geçiş adımlarını, kendi tarafınızda savunmacı yazmanın kurallarını, izleme sinyallerini, geri alma planını ve güncellememenin ne zaman doğru karar olduğunu ele alıyoruz.

1Duyuru2Envanter3Etki analizi4Test5Geçiş6İzleme

Entegrasyonlar neden sessizce kırılır?

Kırılmanın üç türü vardır ve üçü çok farklı hızlarda fark edilir. Gürültülü kırılma açıktır: kimlik doğrulama reddedilir, uç nokta kaybolur, bağlantı hata döndürür. Bunlar can sıkıcıdır ama kendini haber verir. Sessiz kırılma ise arayüzün hâlâ başarılı yanıt döndürdüğü, buna karşılık içeriğin değiştiği durumdur; sisteminiz her şeyin yolunda olduğunu düşünür. Üçüncüsü gecikmeli kırılmadır: kota daralır, sayfalama davranışı değişir, sistem yalnızca yoğun saatlerde ve kısmen veri kaybeder.

Sessiz kırılmanın tehlikesi alarm üretmemesi değil, veri üretmeye devam etmesidir. Boş gelen bir alan raporda sıfır olarak toplanır, yanlış anlamı olan bir değer segmentasyonu bozar, eksik bir bağlantı kaydı ilişkiyi yanlış müşteriye asar. Fark edildiğinde artık iki iş vardır: entegrasyonu düzeltmek ve geriye dönük olarak kirlenmiş veriyi temizlemek. İkincisi neredeyse her zaman daha uzun sürer.

Asıl maliyet de burada ortaya çıkar. Kırık bir entegrasyon veriyi kaybettirmekten çok, güveni kaybettirir. Bir kez yanlış çıkmış bir rapor, düzeltildikten sonra bile bir süre sorgulanır; ekip sayıya değil, sayının nereden geldiğine bakmaya başlar. Otomasyonların sağlığı üzerine kurulmuş bütün düzen, tek bir sessiz kırılmadan sonra elle kontrol alışkanlığına geri döner.

Sağlayıcılar sürümü nasıl işaretler?

Yaygın üç kalıp var. Birincisi adres içinde sürüm taşımaktır; ikinci sürüm ayrı bir yolda yayınlanır ve siz hazır olduğunuzda geçersiniz. İkincisi tarih damgalı sürümlemedir: hesabınız belirli bir tarihe sabitlenir, yeni davranışlar yalnızca o tarihi ileri aldığınızda gelir. Üçüncüsü istek başlığıyla sürüm belirtmektir. Hangi kalıp olursa olsun, kritik olan sizin hangi sürümde olduğunuzu bilmenizdir; çoğu ekip bunu ilk kez bir şey kırıldığında öğrenir.

Bir de sürüm numarasının hiç değişmediği, ama alan düzeyinde kullanımdan kaldırmanın işlediği durum var. Sağlayıcı bir alanı önce isteğe bağlı yapar, sonra boş döndürür, en sonunda kaldırır. Bu üç adımın arasında aylar olabilir ve hiçbiri sürüm numarasına yansımaz. Sözleşmede yazan uyumluluk sözü burada işe yaramaz, çünkü kırıcı değişikliğin tanımı taraflara göre farklıdır: sağlayıcı için yeni bir alan eklemek eklemedir, sizin için zorunlu alan doğrulamanızı bozan bir kırılmadır.

Sürüm numarası ne söyler, ne söylemez

Yeni bir ana sürüme geçmek tek seferlik bir proje gibi planlanır, oysa asıl risk aynı ana sürümün içinde birikir. Bir listeye yeni bir durum değeri eklenmesi, bir tarihin farklı bir saat diliminde dönmeye başlaması, bir metin alanının uzunluk sınırının artması: hiçbiri sürüm numarasını değiştirmez, üçü de sizin tarafınızda kırılma yaratabilir. Doğru soru şudur: kodunuz daha önce hiç görmediği bir değerle karşılaştığında ne yapıyor? Cevap sessizce yok saymaksa, ilk sessiz kırılmanız zaten yazılmış demektir.

Kırılma türleri ve fark edilme süreleri

Bir geçiş planı yapmadan önce, hangi tür kırılmanın sizi ne kadar sürede bulacağını görmek işe yarar. Aşağıdaki dağılım, nereye alarm koyacağınızı da belirler.

Kırılma türü	Nasıl fark edilir	Tipik gecikme
Kimlik doğrulama reddi	Hata günlüğü, anında	Saatler
Uç nokta kaldırıldı	Hata günlüğü, anında	Saatler
Alan kaldırıldı, boş dönüyor	Rapor tutarsızlığı	Haftalar
Alanın anlamı veya biçimi değişti	Yanlış veri birikimi	Haftalar veya aylar
Kota veya hız limiti daraldı	Yoğun saatlerde kısmi kayıp	Günler

Tablodaki ilk iki satır aslında iyi haberdir: sistem size bağırır. Asıl para ortadaki iki satırda kaybedilir, çünkü orada kimse bağırmaz. Bu yüzden izleme yatırımını hata günlüğüne değil, veri şeklinin kendisine yapmak gerekir; bağlantı sağlığını hangi sinyallerle takip edeceğinizi entegrasyon izleme yazısında ayrıntılı anlatıyoruz.

Elinizde ne olduğunu bilmeden hiçbir geçiş planlanamaz

Çoğu şirkette entegrasyon sayısı, sorulduğunda verilen cevabın belirgin biçimde üstündedir. Resmî olarak kurulmuş üç bağlantının yanında, bir kampanya için açılmış bir otomasyon senaryosu, bir stajyerin kurduğu tablo senkronu ve pazarlamacının kendi hesabıyla bağladığı bir form aracı durur. Bunların hiçbiri belgelenmemiştir ve hepsi bir sürüm değişikliğinde kırılabilir.

• Bağlantı adı ve yönü: Veri hangi sistemden hangisine akıyor ve tek yönlü mü çift yönlü mü; yön bilgisi olmadan etki analizi yapılamaz.
• Kullanılan sürüm ve uç noktalar: Hangi sürümde olduğunuz ve hangi uç noktaları çağırdığınız yazılı olmalı, çünkü duyurular uç nokta bazında yapılır.
• Sahibi: Bağlantının bir kişi değil, bir rol sahibi olmalı; kişiye bağlı sahiplik ilk ayrılmada boşa düşer.
• Kimlik bilgisi türü ve geçerlilik süresi: Anahtar mı, yetkilendirme akışı mı, ne zaman süresi doluyor; süresi dolan bir anahtar tıpkı bir sürüm değişikliği gibi görünür.
• İş etkisi: Bu bağlantı bugün dursa ne olur; cevabı hiçbir şey ise o bağlantıyı korumak için harcanacak emek de sıfırdır.
• Son başarılı çalışma zamanı: Bir bağlantının canlı olup olmadığını gösteren tek nesnel veri budur; kurulu olması çalıştığı anlamına gelmez.
• Elle yedek çözüm: Bağlantı üç gün kapalı kalırsa işin nasıl yürüyeceği önceden yazılmalı, kriz anında icat edilmemelidir.

Envanterin en çok atlanan satırı sahipliktir. Bağlantılar çoğu zaman bir kişinin hesabıyla, o kişinin e-posta adresiyle ve o kişinin bildiği bir anahtarla kurulur. O kişi ayrıldığında bağlantı bir süre daha çalışmaya devam eder, sonra sessizce ölür. Anahtarların kişiye değil kuruma bağlanması gerektiğini API anahtarı ve güvenli erişim yönetimi yazısında ele alıyoruz; sürüm yönetiminin ilk adımı aslında budur.

Duyuruyu kim alıyor?

Sağlayıcılar kullanımdan kaldırma duyurusunu genellikle hesapta kayıtlı teknik iletişim adresine gönderir. O adres çoğu KOBİ'de bir insanın kişisel iş adresidir ve o insan bir yıl sonra başka bir yerde çalışıyordur. Duyuru gider, kimse okumaz, tarih geçer. Bunun çözümü basittir ve on dakika sürer: bütün sağlayıcı hesaplarında teknik iletişim adresini kalıcı bir grup adresine çevirin, o adresi de en az iki kişinin okuduğu bir yere yönlendirin.

İkinci nokta satın alma anına aittir. Sözleşmelerde erişilebilirlik taahhüdü genelde bulunur; kullanımdan kaldırma penceresi taahhüdü neredeyse hiç bulunmaz. Yani sağlayıcı size ayda kaç dakika kesinti yapabileceğini söyler ama bir arayüzü ne kadar önceden haber vererek kapatabileceğini söylemez. Bu soruyu değerlendirme aşamasında sormak, sonradan sormaktan çok daha ucuzdur; konunun bağımlılık boyutunu tedarikçiye bağımlılık ve veri taşınabilirliği yazısında açıyoruz.

Test: sanal ortam ne işe yarar, ne işe yaramaz

Sağlayıcıların test ortamı yeni sürümün çalıştığını gösterir; sizin verinizle çalıştığını göstermez. Test ortamındaki kayıtlar temizdir: her alan dolu, her tarih biçimli, her metin kısa. Gerçek verinizde ise yıllar içinde birikmiş yarım kayıtlar, iki farklı biçimde girilmiş telefonlar ve kimsenin doldurmadığı zorunlu alanlar vardır. Geçişte kırılan şey neredeyse her zaman bu kuyruktur. Test ve değişiklik ortamının nasıl kurulacağını sandbox ve değişiklik yönetimi yazısında anlatıyoruz.

Kabul kriteri de somut olmalıdır. En işe yarar yöntem karşılaştırmalı çalıştırmadır: aynı kayıt kümesini eski ve yeni sürümle okuyup çıktıları alan alan karşılaştırın. Fark listesi çıktığında iki tür fark görürsünüz: beklenen farklar ve açıklayamadığınız farklar. Geçişi ancak ikinci liste boşaldığında yapın. Alanların iki taraf arasında nasıl hizalanacağını alan eşleme yazısında adım adım ele alıyoruz.

Kendi tarafınızda savunmacı yazmak

Sürüm değişikliklerine karşı en iyi koruma, sağlayıcının disiplini değil sizin okuma biçiminizdir. Dört kural çoğu kırılmayı baştan keser. Bilinmeyen bir alan geldiğinde çökmeyin, yok sayın. Beklediğiniz alan eksik geldiğinde varsayılan bir değer uydurmayın; kaydı reddedip kuyruğa alın, çünkü uydurulan varsayılan sessiz kırılmanın ta kendisidir. Tarih ve sayı biçimini asla varsaymayın, açıkça çözümleyin. Dış sistemin kimliğini kendi tarafınızda saklayın ki eşleştirme metne değil kimliğe dayansın.

Bir entegrasyonun en tehlikeli hâli hata vermesi değil, hata vermeden yanlış çalışmasıdır.

Beşinci kural tekrar denemeyle ilgilidir. Bir istek zaman aşımına uğradığında sistem genellikle yeniden dener; karşı taraf ilk isteği aslında işlemişse ortaya çift kayıt çıkar. Her isteğe kendi ürettiğiniz benzersiz bir kimlik iliştirmek ve karşı tarafın bu kimliği tanımasını sağlamak bunu bitirir. Gelen çağrılarda aynı disiplinin güvenlik tarafını webhook güvenliği ve imza doğrulama yazısında topladık.

Çift yönlü akışlarda bir kural daha gerekir: aynı kaydı iki taraf da değiştirdiğinde hangisi kazanır? Bu soruyu sürüm geçişinden önce cevaplamamış ekipler, geçiş sırasındaki gecikmeler yüzünden birbirinin üstüne yazan iki sistemle uğraşır. Çakışma kuralının nasıl kurulacağını iki yönlü veri senkronizasyonu yazısında ele alıyoruz.

İzleme: kırılmayı sizin fark etmeniz gerekir

Üç sinyal, pratikte kırılmaların büyük bölümünü yakalar. Birincisi hacimdir: bu bağlantı normalde saatte kaç kayıt taşır, şu an kaç taşıyor? İkincisi şekildir: taşınan kayıtlarda kritik alanların doluluk oranı düştü mü? Üçüncüsü hata oranıdır, ki zaten en kolay izlenen ve en az bilgi verendir. Kurulum maliyeti en düşük, getirisi en yüksek alarm hacim alarmıdır ve çoğu ekipte hiç kurulmaz.

Hacim alarmının en değerli biçimi sıfır alarmıdır: beklenen bir zaman diliminde hiç kayıt gelmediyse haber ver. Sessiz saatleri hesaba katmak gerekir; gece iki ile beş arasında form gelmemesi normaldir. Kota tarafındaki daralmalar da benzer biçimde hacimde görünür, çünkü limit dolduğunda istekler reddedilir ve kayıt akışı düzleşir. Limitlerin nasıl yönetileceğini API hız limiti ve kota yönetimi yazısında anlatıyoruz.

Geçiş günü: çift çalıştırma ve geri alma

Geçişi tek bir anahtar çevirme anı gibi kurgulamak gereksiz risk yaratır. Daha sağlıklısı gölge dönemdir: yeni sürüm bir hafta boyunca eskisiyle paralel çalışır, çıktıları bir kenara yazılır ama üretimi o değil eski sürüm besler. Bu bir haftada fark listesi kendiliğinden oluşur ve sürprizlerin çoğu üretime dokunmadan görünür hale gelir.

Geri alma planı da yazılı olmalı ve iki şeyi içermelidir: eski sürüme dönüş nasıl yapılır ve bu kararı kim verir. Kararı verecek kişi belirsizse geri dönüş her zaman gecikir. Zamanlama konusunda iki basit kural işe yarar: geçişi cuma yapmayın ve ay sonu kapanış haftasında yapmayın. Aradaki katmanı bir entegrasyon platformuna devretmek sürüm farkını soğurabilir ama gizler de; bu takasın dengesini entegrasyon platformları yazısında tartışıyoruz.

Ne zaman güncellememek doğru karardır?

Yaygın tavsiye her zaman en güncel sürümde kalmayı söyler. Bunun bir sınırı var. Yeni bir ana sürümün ilk haftaları pratikte sağlayıcının genişletilmiş test dönemidir; o dönemde geçen ekip, sağlayıcının hatalarını kendi üretiminde bulur ve düzeltilmesini bekler. Kullanımdan kaldırma penceresi genellikle aylarla ölçülür. Geçişi pencerenin ilk haftasında değil, ortasına yakın bir noktada planlamak hem erken benimseme riskinden hem de son gün telaşından kaçınır.

Bir de hiç güncellememenin doğru olduğu durum var. Yılda birkaç kez çalışan, iş etkisi düşük bir bağlantıyı yeni sürüme taşımak için harcanacak emek, aynı işi kapanış tarihinden sonra elle yapmanın maliyetini aşabilir. Envanterdeki iş etkisi alanı tam olarak bu kararı verdirmek için vardır. Kapatma kararını bilinçli almak, bağlantıyı unutup bir gün çalışmadığını fark etmekten farklıdır; ikisinin arasındaki fark bir cümlelik nottur. Bağlantı kurma seçeneklerinin genel çerçevesini CRM entegrasyonları yazısında bulabilirsiniz.

Nereden başlamalı?

Bu hafta yapılabilecek üç şey var ve üçü de kod gerektirmez. Bir tabloya bütün bağlantıları yazın, her birine bir rol sahibi atayın ve sağlayıcı hesaplarındaki teknik iletişim adresini kalıcı bir grup adresine çevirin. Bu üç adım, sessiz kırılmaların önemli bir bölümünü daha olmadan yakalar; çünkü çoğu kırılma teknik bir eksiklikten değil, duyuruyu kimsenin okumamasından doğar.

Sonraki adım izlemedir: en kritik iki bağlantı için hacim alarmı kurun. Ardından çeyrekte bir, otuz dakikalık bir gözden geçirme oturumu koyun; envanteri açın, sağlayıcıların değişiklik günlüklerine bakın, süresi yaklaşan anahtarları işaretleyin. Bu ritüel bir yıl uygulandığında, kırılmaların büyük kısmı acil durum olmaktan çıkıp planlı işe dönüşür.

Bağlantılarınızı, tetikleyicileri ve kayıtları aynı sistemde tutmak sürüm değişikliklerinin etkisini de küçültür: neyin nereye bağlı olduğunu görmek, envanterin yarısını hazır etmek demektir. Rocketly'de iş akışı otomasyonu, form bağlantıları ve kayıt geçmişi tek yerde duruyor; ücretsiz hesap açarak kendi entegrasyon düzeninizi kurup deneyebilirsiniz.