Güvenli üçüncü taraf API entegrasyonu: yeniden denemeler, zaman aşımı, devre kesiciler

Üçüncü taraf API'lerin çekirdek iş akışlarınızı neden tıkayabileceği

Üçüncü taraf bir API, temiz bir "kapalı" olayına benzemeyen şekillerde başarısız olabilir. En yaygın sorun yavaşlıktır: istekler takılır, yanıtlar gecikir ve uygulamanız beklemeye devam eder. Bu çağrılar kritik yolda ise, dışarıdaki küçük bir aksaklık sisteminizin içine yığılır.

Böylece yerel bir yavaşlama tam bir kesintiye dönüşür. İş parçacıkları veya çalışanlar beklemede kalır, kuyruklar büyür, veritabanı işlemleri daha uzun açık kalır ve yeni istekler zaman aşımına uğrar. Kısa sürede, harici API'yi kullanmayan sayfalar bile bekleyen işler yüzünden bozuk gibi hissedilir.

Etkisi somuttur. Güvenilmez bir kimlik sağlayıcı kayıtları ve girişleri engeller. Bir ödeme ağ geçidi zaman aşımına uğrarsa ödeme tamamlanmaz ve kullanıcılar ücretlendirilip ücretlendirilmediklerinden emin olamaz. Mesajlaşma gecikmesi parola sıfırlamalarını ve sipariş onaylarını durdurur; bu da yeni yeniden denemelere ve destek biletlerine yol açar.

Amaç basit: harici hataları izole etmek, böylece çekirdek iş akışları hareket etmeye devam eder. Bu, bir kullanıcının sipariş vermesine izin verip ödemeyi sonra doğrulamak veya hoş geldin e-postası başarısız olsa bile kaydı kabul etmek anlamına gelebilir.

Pratik bir başarı ölçütü: bir sağlayıcı yavaşladığında veya kapandığında uygulamanız yine de hızlı ve net yanıt vermeli ve etki alanı küçük kalmalıdır. Örneğin, çoğu çekirdek istek normal gecikme bütçeniz içinde tamamlanmalı, hatalar yalnızca gerçekten o API'ye bağlı özelliklerle sınırlı kalmalı, kullanıcılara açık bir durum gösterilmeli (kuyrukta, beklemede, daha sonra deneyin) ve sağlayıcı geri döndüğünde kurtarma otomatik olmalıdır.

Planlamanız gereken hata modları

Çoğu hata tahmin edilebilirdir, zamanlamaları değil ama türleri. Onları baştan adlandırın ve neyi yeniden deneyeceğinize, neyi durduracağınıza ve kullanıcıya ne göstereceğinize karar verin.

Yaygın kategoriler:

• Gecikme sıçramaları (isteklerin aniden 10 kat daha uzun sürmesi)
• Geçici sunucu veya ağ hataları (zaman aşımı, 502/503, bağlantı sıfırlamaları)
• Oran sınırları ve kota tükenmesi (429, günlük limitler)
• Kimlik doğrulama ve izin problemleri (süresi dolmuş anahtarlar, iptal edilmiş erişim)
• Kötü veya beklenmedik veri (eksik alanlar, yanlış formatlar, kısmi yanıtlar)

Tüm hatalar aynı anlama gelmez. Geçici sorunlar genellikle yeniden denemeye değer çünkü bir sonraki çağrı başarılı olabilir (ağ kesintileri, zaman aşımı, 502/503 ve bekledikten sonra bazı 429'lar). Kalıcı sorunlar genellikle kendi kendine düzelmez (geçersiz kimlik bilgileri, yanlış uç noktalar, hatalı istekler, izin reddi).

Her hatayı aynı şekilde ele almak küçük bir olayı kesintiye dönüştürür. Kalıcı hataları yeniden denemek zaman kaybıdır, oran sınırlarına çabuk ulaşır ve her şeyi yavaşlatan birikmiş iş oluşturur. Hiç yeniden denememek ise kullanıcıların işlemleri tekrar etmesine zorlar ve birkaç saniye sonra tamamlanabilecek işleri düşürür.

Ödeme, giriş, parola sıfırlama ve bildirimler (e-posta/SMS/push) gibi duraklamanın arızaya benzedüğü iş akışlarına ekstra dikkat gösterin. Pazarlama API'sinde iki saniyelik bir sıçrama sinir bozucu olabilir. Ödeme yetkilendirmesinde iki saniyelik bir sıçrama geliri engeller.

Yardımcı bir test: "Bu çağrının kullanıcının ana görevini şu anda tamamlaması için bitmesi gerekli mi?" Eğer evet ise, sıkı zaman aşımı, dikkatli yeniden denemeler ve net bir hata yolu gerekir. Eğer hayır ise, işi bir kuyruğa kaydırın ve uygulamayı duyarlı tutun.

Zaman aşımı: bir sınır seçin ve ona bağlı kalın

Zaman aşımı, durup devam etmeden önce ne kadar beklemeye razı olduğunuzdur. Belirgin bir sınır olmadan, tek bir yavaş sağlayıcı bekleyen istekleri yığar ve önemli işi engeller.

Beklemeyi iki türde ayırmak işe yarar:

• Bağlantı zaman aşımı: bir bağlantı kurmak için ne kadar süre deneyeceğiniz.
• Okuma zaman aşımı: bağlandıktan sonra bir yanıt beklemek için ne kadar süre bekleyeceğiniz.

Sayıları seçmek mükemmellik meselesi değil. İnsan sabrı ve iş akışınızla eşleşmesi önemlidir.

• Bir kullanıcı dönen bir yükleniyor işareti izliyorsa genelde hızlı bir cevap ve net bir sonraki adım gerekir.
• Arka plan işi ise (örneğin faturaları gece senkronize etmek) daha fazla zaman tanıyabilirsiniz, ama yine de sonsuza kadar takılamayacağı bir tavan olmalı.

Zaman aşımını seçmenin pratik yolu deneyimden geriye doğru çalışmaktır:

• Bir kullanıcı ne kadar bekleyebilir ve ne zaman net bir mesaj göstermeniz gerekir?
• Bu çağrı şimdi başarısız olursa, daha sonra yeniden deneyebilir veya bir yedeğe başvurabilir misiniz?
• Zirvede kaç tane çağrı çalışıyor?

Takası gerçektir. Çok uzun süre beklemek iş parçacıkları, çalışanlar ve veritabanı bağlantılarını bağlar. Çok kısa olmak ise yanlış başarısızlıklara ve gereksiz yeniden denemelere yol açar.

Kesintileri kötüleştirmeyen yeniden denemeler

Yeniden denemeler, bir başarısızlık muhtemelen geçici olduğunda yardımcı olur: kısa süreli ağ sorunu, DNS aksaması veya tek seferlik 500/502/503 gibi. Bu durumlarda, ikinci bir deneme başarılı olabilir ve kullanıcılar hiç fark etmez.

Risk, yeniden deneme fırtınasıdır. Birçok istemci aynı anda başarısız olur ve hepsi birlikte yeniden denerse sağlayıcıyı (ve kendi çalışanlarınızı) boğabilir. Backoff ve jitter bunu önler.

Bir yeniden deneme bütçesi sizi disiplinli tutar. Denemeleri düşük tutun ve toplam zamanı sınırlayın ki çekirdek iş akışları başkalarını bekleyerek sıkışmasın.

Güvenli bir varsayılan yeniden deneme tarifi

• Yalnızca birkaç kez yeniden deneyin (akışa göre genelde toplam 1-3 deneme).
• Üssel backoff kullanın (örneğin 200ms, 500ms, 1s) artı rastgele jitter.
• Yeniden denemeye harcanan toplam zamanı sınırlayın (kullanıcı etkileşimli akışlarda genelde birkaç saniye).
• Tüm denemeler için tek uzun zaman aşımı yerine her deneme için ayrı bir zaman aşımı kullanın.

400/422 doğrulama hataları, 401/403 kimlik sorunları veya 404 gibi öngörülebilir istemci hatalarını yeniden denemeyin. Bunlar neredeyse her seferinde yine başarısız olur ve sadece yük ekler.

Bir başka koruyucu: bir işlemi (POST/PUT) yalnızca idempotency uygulandıysa yeniden deneyin; aksi halde çift ücretlendirme veya yinelenen kayıt riski vardır.

Idempotency: yeniden denemeleri gerçek iş akışları için güvenli hale getirin

Idempotency, aynı isteği iki kez güvenle çalıştırıp aynı nihai sonucu alabilmek demektir. Bu önemlidir çünkü yeniden denemeler normaldir: ağlar düşer, sunucular yeniden başlar ve istemciler zaman aşımına uğrar. Idempotency yoksa "yardımcı" bir yeniden deneme çoğaltmalar ve gerçek maddi problemler yaratır.

Ödeme işlemini düşünün: ödeme API'si yavaş, uygulamanız zaman aşımına uğruyor ve siz yeniden deniyorsunuz. Eğer ilk çağrı aslında başarılı olduysa, yeniden deneme ikinci bir ücretlendirme oluşturabilir. Aynı risk sipariş oluşturma, abonelik başlatma, e-posta/SMS gönderme, iade yapma veya destek bileti oluşturma gibi işlemlerde de vardır.

Çözüm: her "bir şey yap" çağrısına bir idempotency anahtarı (veya istek ID'si) ekleyin. Bu anahtar kullanıcı eylemi başına benzersiz olmalı, deneme başına değil. Sağlayıcı (veya kendi servisinizi kullanıyorsanız siz) bu anahtarı çoğaltmaları algılamak ve aynı sonucu döndürmek için kullanır, böylece işlemi tekrar yapmaz.

Idempotency anahtarını bir başlık olarak değil, veri modelinin bir parçası gibi ele alın.

Üretimde tutarlı kalan bir desen

Kullanıcı eylemini başlattığında (örneğin Öde butonuna basıldığında) bir anahtar oluşturun ve bunu yerel kaydınızla saklayın.

Her denemede:

• Aynı anahtarı gönderin.
• Aldığınız nihai sonucu saklayın (başarı yanıtı, hata kodu, ödeme ID'si).
• Eğer zaten kayıtlı bir sonuç varsa, eylemi tekrar etmek yerine o sonucu döndürün.

Eğer dahili çağrılar için "sağlayıcı" sizseniz, aynı davranışı sunucu tarafında zorunlu kılın.

Devre kesiciler: API başarısız olduğunda çağrıyı durdurun

Devre kesici bir güvenlik anahtarıdır. Harici bir hizmet başarısız olmaya başladığında, muhtemelen zaman aşımına uğrayacak daha fazla isteği üst üste bindirmek yerine kısa bir süre çağrıları durdurursunuz.

Devre kesiciler genelde üç durumda çalışır:

• Kapalı (Closed): istekler normal akışta devam eder.
• Açık (Open): çağrılar soğuma penceresi için engellenir.
• Yarı açık (Half-open): soğuma sonrası küçük bir sayıda test çağrısı hizmetin toparlanıp toparlanmadığını kontrol eder.

Devre açıkken uygulamanız tahmin edilebilir bir şey yapmalı. Kayıt sırasında adres doğrulama API'si kapalıysa adresi kabul edip daha sonra gözden geçirmek üzere işaretleyin. Ödeme risk kontrolü kapalıysa siparişi manuel incelemeye alın veya o seçeneği geçici olarak devre dışı bırakıp durumu açıklayın.

Etkisini kullanıcıya uygun eşiklerle seçin:

• ardışık hatalar (örneğin 5 başarısızlık ard arda)
• kısa bir pencerede yüksek hata oranı
• çok sayıda yavaş yanıt (zaman aşımı)
• belirli durum kodları (tekrarlayan 503 gibi)

Soğuma sürelerini kısa tutun (saniyeler ila bir dakika) ve yarı-açık testleri sınırlı tutun. Amaç önce çekirdek iş akışlarını korumak, sonra hızlıca toparlanmaktır.

Yedekler ve kuyruklar: uygulamayı kullanılabilir tutun

Harici bir API yavaş veya kapalı olduğunda hedefiniz kullanıcıyı hareket ettirmeye devam ettirmektir. Bu, ne olduğunu dürüstçe söyleyen bir B Planınızın olması anlamına gelir.

Yedekler: "yeterince iyi" bir deneyim seçin

Yedek, API zamanında yanıt veremediğinde uygulamanızın yaptığı şeydir. Seçenekler arasında önbelleğe alınmış veriyi kullanmak, bozulmuş modu açmak (önemsiz bileşenleri gizlemek, isteğe bağlı eylemleri devre dışı bırakmak), API çağrısı yerine kullanıcıdan manuel girdi istemek (manuel adres girişi) veya bir sonraki adımla birlikte net bir mesaj göstermek bulunur.

Dürüst olun: tamamlandı demeyin eğer tamamlanmadıysa.

Kuyruklar: "şimdi" gerekli değilse daha sonra yapın

İşin kullanıcı isteği içinde bitmesi gerekmiyorsa, işi bir kuyruğa atın ve hızlı yanıt verin. Yaygın adaylar: e-posta gönderimi, CRM'e senkronizasyon, rapor üretimi ve analiz olaylarının gönderimi.

Çekirdek eylemler için hızlı başarısızlık. Bir API ödeme (veya hesap oluşturma) tamamlamak için gerekliyse, isteği engellemeyin; siparişi kabul edin, harici çağrıyı kuyruğa atın ve sonradan mutabık kalın. Eğer API gereklisiyse (örneğin ödeme yetkilendirmesi), net bir mesajla hızlıca başarısız olun ve kullanıcıyı bekletmeyin.

Kullanıcının gördüğü arka planda olanlarla eşleşmeli: net bir durum (tamamlandı, beklemede, hatalı), yerine getirilebilir bir söz (makbuz şimdi, onay sonra), yeniden deneme yolu ve kullanıcı arayüzünde görünür kayıt (etkinlik günlüğü, bekleyen rozeti).

Oran sınırları ve yük: kendi kendinize verdiğiniz hatalardan kaçının

Oran sınırları sağlayıcının, "Bizi çağırabilirsiniz ama çok sık değil" demesinin yoludur. Onlara sandığınızdan daha çabuk takılacaksınız: trafik sıçramaları, arka plan işlerinin aynı anda tetiklenmesi veya hatada döngüye giren bir bug.

Başlangıç olarak ürettiğiniz istek sayısını kontrol edin. Mümkünse toplu çağrı yapın, güvenliyse yanıtları 30-60 saniye önbelleğe alın ve uygulamanızın sağlayıcıdan daha hızlı patlamamasını sağlamak için istemci tarafında throttle uygulayın.

429 Too Many Requests aldığınızda, bunu yavaşlama sinyali olarak ele alın.

• Retry-After sağlanmışsa saygı gösterin.
• Birçok çalışanın aynı anda yeniden denemesini önlemek için jitter ekleyin.
• 429'lar için yeniden denemeleri sınırlandırın.
• Tekrarlayan 429'larda daha agresif geri çekilin.
• Oluşumları metrik olarak kaydedin ki kullanıcılar fark etmeden önce siz patternleri görün.

Ayrıca eşzamanlılığı sınırlayın. Tek bir iş akışı (örneğin kişi senkronizasyonu) her çalışan yuvasını tüketmemeli ve giriş veya ödeme gibi kritik akışları aç bırakmamalı. Ayrı havuzlar veya özellik başına sınırlar yardımcı olur.

Adım adım: güvenli bir varsayılan entegrasyon tarifi

Her üçüncü taraf çağrısının bir hata planı olmalı. Mükemmellik gerekmez; sağlayıcının kötü bir günü olduğunda tahmin edilebilir davranış gerekir.

1) Çağrıyı sınıflandırın (olmazsa olmaz vs bekleyebilir)

Çağrı şimdi başarısız olursa ne olacağını kararlaştırın. Ödemede vergi hesaplaması olmazsa olmaz olabilir. Pazarlama kişi senkronizasyonu genelde bekleyebilir. Bu seçim geri kalanları yönlendirir.

2) Zaman aşımı ve yeniden deneme bütçesi belirleyin

Çağrı türüne göre zaman aşımı seçin ve tutarlı tutun. Sonra bir yeniden deneme bütçesi belirleyin ki yavaş bir API'ye sürekli vurmayın.

• Olmazsa olmaz, kullanıcı bekliyor: kısa zaman aşımı, 0-1 yeniden deneme.
• Bekleyebilir, arka plan işi: daha uzun zaman aşımı, backoff ile birkaç yeniden deneme.
• Asla sonsuza kadar yeniden deneme yapmayın: görev başına harcanan toplam zamanı sınırlandırın.

3) Yeniden denemeleri idempotency ve takip ile güvenli hale getirin

Bir istek bir şey oluşturabiliyorsa veya ücretlendirme yapıyorsa idempotency anahtarları ekleyin ve istek kaydı saklayın. Ödeme isteği zaman aşımına uğrarsa, yeniden deneme çift ücretlendirme yapmamalı. Takip aynı zamanda destek ekibinin "Geçti mi?" sorusuna yanıt vermesine yardımcı olur.

4) Devre kesici ve yedek davranış ekleyin

Hatalar sıçradığında sağlayıcıyı kısa bir süre çağırmayın. Olmazsa olmaz çağrılarda net bir "Tekrar dene" yolu gösterin. Bekleyebilir çağrılarda işi kuyruğa atın ve sonra işleyin.

5) Temel metrikleri izleyin

Gecikme, hata oranı ve devre kesici açık/kapalı olaylarını izleyin. Uyarıları tek atlamalara değil, sürdürülen değişimlere göre kurun.

Küçük bir sorunu kesintiye çeviren yaygın hatalar

Çoğu API kesintisi büyük başlamaz. Uygulamanız en kötü şekilde tepki verdiği için büyük olur: çok uzun bekler, çok agresif yeniden dener ve her şeyi çalıştıran aynı çalışanları bağlar.

Bu desenler zincirleme etkiye yol açar:

• Her hatayı yeniden denemek, 4xx hataları dahil (geçersiz istekler, süresi dolmuş kimlik, izin eksikliği).
• Çok uzun zaman aşımı ayarlamak "güvenli olsun diye" ve bu da iş parçacıklarını, DB bağlantılarını veya iş çalıştırıcılarını sessizce tüketir.
• Idempotency anahtarı olmadan oluşturma işlemlerini yeniden denemek, çift ücretlendirme veya yinelenen kayıtlar oluşturur.
• Yanlış yapılandırılmış devre kesiciler hiç toparlanmaz veya sürekli açılıp kapanır.
• Kısmi kesintileri tüm sistemi etkileyecek şekilde ele almak yerine sadece etkilenen özelliği bozmadan degrade edin.

Küçük düzeltmeler büyük kesintileri önler: yalnızca geçici olma olasılığı yüksek hataları yeniden deneyin (zaman aşımı, bazı 429'lar, bazı 5xx'ler) ve denemeleri backoff ve jitter ile sınırlayın; zaman aşımını kısa ve kasıtlı tutun; ücretlendirme/oluşturma için idempotency şart koşun; ve kısmi kesintilere göre tasarlayın.

Yayına almadan önce hızlı kontrol listesi

Bir entegrasyonu üretime göndermeden önce hata zihniyetiyle hızlı bir kontrol yapın. Bir maddeye "evet" diyemiyorsanız, kayıt, ödeme veya mesaj gönderme gibi çekirdek iş akışları için bunu bir sürüm engelleyicisi olarak görün.

• Zaman limitleri açık (bağlantı zaman aşımı ve okuma/yanıt zaman aşımı).
• Yeniden denemeler sınırlı (küçük yeniden deneme bütçesi, backoff, jitter ve toplam zaman sınırı).
• Yeniden denemeler gerçek eylemler için güvenli (idempotency anahtarları veya net dedupe kontrolleri).
• Bir devre kesici ve bir B Planı var (yedek, degrade modu veya kuyruk).
• Sorunları erken görebiliyorsunuz (sağlayıcı ve uç nokta bazında gecikme, hata oranı ve bağımlılık sağlığı).

Eğer bir ödeme sağlayıcısı zaman aşımına başlarsa doğru davranış "checkout yine yüklenir, kullanıcıya net bir mesaj gösterilir ve sonsuza kadar beklemezsiniz" olmalı; "her şey zaman aşımına kadar takılır" değil.

Örnek: bir sağlayıcı güvenilmez olduğunda checkout'u korumak

Bir checkout'ın üç servise çağrı yaptığını hayal edin: kartı tahsil etmek için bir ödeme API'si, vergi hesaplamak için bir vergi API'si ve makbuzu göndermek için bir e-posta API'si.

Ödeme çağrısı tek senkron olması gereken çağrıdır. Vergi veya e-posta sorunları satın almayı tıkamamalıdır.

Vergi API'si yavaşsa

Vergi API'si bazen 8-15 saniye sürüyorsa checkout beklerse kullanıcılar sepeti terk eder ve uygulama çalışanları bağlar.

Daha güvenli bir akış:

• Sert bir zaman aşımı belirleyin (örneğin 800ms ila 2s) ve hızlıca başarısız olun.
• En fazla bir kez yeniden deneyin, yalnızca güvenliyse, jitter ile.
• Zaman aşımı olursa alıcının bölgesi için önbelleğe alınmış bir oran veya son bilinen tablosunu kullanın.
• Yasal olarak önbelleğe alınmış oranları kullanamıyorsanız, siparişi "vergi beklemede" olarak işaretleyin ve yeniden hesaplama kuyruğa alın.

Sonuç: vergi sağlayıcısı yavaş olduğunda daha az terk edilmiş sepet ve daha az takılı sipariş.

E-posta API'si kapalıysa

Makbuz e-postası önemli ama asla ödeme yakalamayı engellememeli. E-posta API'si hatalıysa devre kesici birkaç hızlı başarısızlıktan sonra açılmalı ve kısa bir soğuma penceresi boyunca çağrılar durdurulmalıdır.

E-postayı satır içinde göndermek yerine, bir idempotency anahtarı ile "makbuz gönder" işini kuyruğa atın (örneğin order_id + email_type). Sağlayıcı kapalıysa, kuyruk arka planda yeniden denemeye devam eder ve müşteri yine de başarılı bir satın alma görür.

Sonuç: eksik onaylardan kaynaklı daha az destek talebi ve ödeme dışı nedenlerle checkout'un başarısız olması nedeniyle kaybedilen gelir olmaz.

Sonraki adımlar: bunları uygulamaya güvenli şekilde yaymak

En çok zarar veren bir iş akışını seçin (checkout, kayıt, faturalama) ve onu referans entegrasyonunuz yapın. Sonra aynı varsayılanları her yere kopyalayın.

Basit bir yayılma sırası:

• Zaman aşımı ayarlarını yapın ve hızlıca başarısız olun, net bir hata gösterin.
• Yeniden denemeler ekleyin; yalnızca yeniden denemeye uygun hatalar için backoff ile.
• Yeniden denemelerin çift ücretlendirme yapmaması için idempotency ekleyin.
• Kötü bir sağlayıcının çekirdek iş akışınızı tıkamasını önlemek için devre kesiciler ekleyin.

Varsayılanlarınızı yazın ve onları sıkıcı tutun: bir bağlantı zaman aşımı, bir istek zaman aşımı, maksimum yeniden deneme sayısı, backoff aralığı, devre kesici soğuma süresi ve neyin yeniden deneneceğine dair kurallar.

Bir sonraki iş akışına genişletmeden önce bir hata tatbikatı yapın. Zaman aşımı zorlayın (veya test ortamında sağlayıcıyı engelleyin), sonra kullanıcının faydalı bir mesaj gördüğünü, yedek yolların çalıştığını ve kuyruktaki yeniden denemelerin sonsuza kadar birikmediğini doğrulayın.

Eğer yeni ürünleri hızlıca inşa ediyorsanız, bu güvenilirlik varsayılanlarını yeniden kullanılabilir bir şablona dönüştürmek faydalıdır. Koder.ai (koder.ai) kullanan takımlar için bu genelde zaman aşımı, yeniden deneme, idempotency ve devre kesici kurallarını bir kez tanımlamak ve sonra yeni servislerde aynı deseni uygulamak anlamına gelir.",