API entegrasyonu öngörülebilir biçimde başarısız olur ve çözüm hep aynı biçimdedir: bir mesajın tam olarak bir kez teslim edildiğini garanti edemezsiniz, bu yüzden bunun yerine işlemeyi tam olarak bir kez yaparsınız. Idempotency mükerrerleri, yeniden denemeler dakikalık arızaları, tekrar oynatma saatlik arızaları ve mutabakat geri kalan her şeyi karşılar. Bu dördünden biri eksik olan bir entegrasyon er ya da geç çift tahsilat, kayıp sipariş veya sessizce çelişen iki sistem üretir.
Bu rehber arıza biçimlerini, onları sınırlayan desenleri, bir entegrasyonun dürüstçe nasıl fiyatlanacağını ve kod yazılmadan önce nelerin tanımlanması gerektiğini kapsar.
Önemli noktalar
- En az bir kez teslimi varsayın: Sağlayıcılar yeniden gönderir; işleyiciniz ikinci denemede de birinciyle aynı sonucu üretmelidir.
- Hızlı yanıtlayın, sonra işleyin: Yükü kabul edin, onaylayın ve işi arka plan işçisinde yapın.
- Mutabakatı ihtiyaç duymadan önce kurun: Günlük karşılaştırma, yeniden denemelerin asla yakalayamayacağını yakalar.
- Her bağlantıyı ayrı fiyatlandırın: "Entegrasyonlar" için tek satır, aşımın en güvenilir habercisidir.
Kod yazmadan önce şu dördünü tanımlayın
Doğruluk kaynağı. İki tarafta da bulunan her alan için, çeliştiklerinde hangi sistem kazanır. Bu yazılı olmadığında yanıt, en son hangi kod çalıştıysa o olur.
Yön ve tetikleyici. İtme mi çekme mi, gerçek zamanlı mı toplu mu ve neyin başlattığı. "Çalışmayı bırakan" entegrasyonların çoğu, kimsenin izlemediği zamanlanmış işlerdi.
Hata davranışı. Diğer sistem yavaş, erişilemez olduğunda veya beklenmedik bir yanıt döndürdüğünde ürünün ne yapacağı. Bu bir iş kararıdır: kullanıcıyı engelliyor musunuz, işi kuyruğa mı alıyorsunuz, yoksa devam edip sonra mı uzlaştırıyorsunuz?
Sahip. Her iki tarafta bozulduğunda aranacak adı belli bir kişi ve özgün geliştiriciyi gerektirmeyen bir çalıştırma kılavuzu.
Arıza biçimleri ve her birinin gerektirdiği
| Arıza | Nasıl görünür | Çözüm |
|---|---|---|
| Mükerrer teslim | Aynı olay iki kez işlenir; çift tahsilat veya mükerrer kayıt | Her yazmadan önce saklanan ve kontrol edilen idempotency anahtarı |
| Geçici kesinti | Birkaç dakika 500 veya zaman aşımı | Sıçramalı üstel geri çekilme, sınırlı deneme |
| Hız sınırlama | Yük altında 429 yanıtları | Geri baskıya uyun; daha sert denemek yerine yavaşlayın |
| Şema değişikliği | Alanlar habersiz yeniden adlandırılır veya kaldırılır | Sözleşme testleri; sessizce düşürmek yerine doğrulayıp uyarın |
| Sessiz ayrışma | İki sistem de çalışır, toplamlar tutmaz | Kaynağa karşı zamanlanmış mutabakat |
| Kalıcı hata | Yeniden denemeler tükendi | Sahibi ve inceleme süreci olan ölü mektup kuyruğu |
En yaygın tasarım hatası, uygulayıcıların politika düzleştirme dediği şeydir: her hatayı tek bir yeniden deneme yoluna toplamak. Kota hatası ile geçici sunucu hatası zıt yanıtlar gerektirir ve ikisini aynı saymak bir hız sınırını yeniden deneme fırtınasına çevirir.
Her yazmayı idempotent yapın
Sağlayıcılar en az bir kez teslim garanti eder; bu da mükerrerlerin olay değil olağan işleyiş olduğu anlamına gelir. Gelen bir olayın tetiklediği her veritabanı yazması, aynı olay kimliğiyle ikinci kez çalıştığında aynı sonucu üretmelidir.
Uygulamada: olay kimliğini alındığında saklayın, işlemeden önce kontrol edin ve kontrol ile yazmayı atomik yapın. Bu olmadan, yeniden gönderilen tek bir webhook mükerrer siparişe, ikinci bir tahsilata veya şu anda destek arayan bir müşteriye giden ikinci onay e-postasına dönüşür.
Bunu bilinçli test edin. Çoğu sağlayıcı tekrar oynatma sunar, aynı olayı üç kez gönderin ve sonucun aynı olduğunu doğrulayın. Yalnızca ilk teslimi kapsayan bir test paketi, mükerrerlerin gelmeye başladığı gün de geçecektir.
Hızlı kabul edin, arka planda işleyin
Yük altında ayakta kalan desen şudur: yükü alın, kuyruğa yazın, hemen başarı yanıtı döndürün ve kuyruktan bir işçide işleyin.
İşi yanıt vermeden önce satır içi yapmak, işleme sürenizi sağlayıcının zaman aşımına bağlar. Yavaş işleme gönderene arıza gibi görünür, bu yeniden denemeyi tetikler, o da ilki hâlâ çalışırken gelir, ve artık performans sorununun üstüne bir eşzamanlılık sorununuz olur.
Kuyruk ayrıca tekrar oynatma sağlar. Bir hata bir günlük işlemeyi bozduğunda, sağlayıcıdan yeniden göndermesini istemek yerine saklanan yüklerden yeniden işlersiniz.
Mutabakatı baştan kurun
Yeniden denemeler dakikaları kapsar. Tekrar oynatma saatleri kapsar. Mutabakat, hiç fark etmediğiniz arızalar dahil geri kalan her şeyi kapsar.
Aynı zaman aralığı için sağlayıcının API'siyle sayıları ve kimlikleri karşılaştıran, boşlukları raporlayıp dolduran bir iş zamanlayın. En az günlük çalıştırın ve birinin rapor okumasını beklemek yerine farkta uyarı verin.
Bu, ekiplerin ilk ciddi olaydan sonra kurduğu parçadır. Önce kurmak çok daha ucuzdur ve bir tutarsızlığı ertesi sabah bulmakla ay sonu kapanışında bulmak arasındaki farktır.
İş diliyle ölçün
Teknik metrikler entegrasyonun çalıştığını söyler. İş metrikleri doğru olduğunu söyler.
Dakikada yazılan sipariş, dakikada geçen ödeme, saatte senkronlanan kayıt, entegrasyon neyi taşımak için varsa onu, izleyin ve sayı normal aralığından saptığında uyarın. 200 döndürürken hiçbir şey yazmayan bir entegrasyon en çok zarar veren arızadır; çünkü her teknik pano sağlıklı olduğunu söyler.
Hataları saymak yerine sınıflandırın: kimlik doğrulama ve imza, hız sınırı, şema, hedef ve iş kuralı reddi; her biri farklı yanıt gerektirir.
Her bağlantıyı ayrı fiyatlandırın
Her entegrasyonun kendi veri modeli, kimlik doğrulama şeması, hata davranışı ve mutabakat gereksinimi vardır. Bunları tek satır olarak tahmin etmek hepsini gizler.
Düz bir bağlantı tipik olarak 2.500–8.000 dolardır; çift yönlü senkronizasyon, karmaşık eşleme veya belgelenmemiş eski bir sistem içeren bağlantı bunun çok üstündedir. Rakamı hareket ettiren değişkenler: API belgeli ve kararlı mı, webhook destekliyor mu yoksa yoklama mı gerektiriyor ve geri yazmanız mı gerekiyor yoksa yalnızca okumanız mı.
Herhangi bir tedarikçiden bağlantıları ayrı fiyatlandırmasını ve en az emin olduğunu adlandırmasını isteyin. Yazılım projeleri en sık entegrasyonda aşar ve tek birleşik rakam, bunu önceden görme imkânınızı ortadan kaldırır.
Güvenlik sözleşmenin parçasıdır
Her istekte webhook imzalarını doğrulayın ve imzasız olanı reddedin. Kimlik bilgilerini yapılandırma yerine bir gizli anahtar yöneticisinde saklayın ve sahibi belli bir takvimle döndürün.
Diğer sistemin ihtiyaç duyduğu asgari veriyi gönderin. Entegrasyonlar zamanla alan biriktirir; çünkü bir alan eklemek kolaydır ve her biri korumaktan ve KVKK ile GDPR kapsamında gerekçelendirmekten sorumlu olduğunuz bir alana dönüşür.
Sağlayıcının değişeceğini planlayın
API'ler değişir. Sürümler kaldırılır, alanlar silinir, hız sınırları daraltılır ve fiyatlandırma yeniden kurgulanır.
Sağlayıcının değişiklik günlüğüne abone olun, en yeniyi takip etmek yerine bir API sürümünü açıkça sabitleyin ve gelen yükleri beklenen bir şemaya karşı doğrulayın; böylece bir değişiklik aylar sonra sessiz bir veri kalitesi sorunu olarak değil, uyarı olarak ortaya çıkar.
İlgili rehberler
- API Entegrasyonu: Planlama, Modeller ve Yaygın Hatalar rehberinin yanında Yapay Zeka İş Akışı Otomasyonu: Kullanım Alanları ve Riskler.
- API Entegrasyonu: Planlama, Modeller ve Yaygın Hatalar rehberinin yanında Özel Yönetim Panosu Geliştirme: Metrikten Aksiyona.
API Entegrasyonu: Planlama, Modeller ve Yaygın Hatalar önümüzdeki üç yılın üzerine kurulabileceği bir platforma yol açıyorsa Platform Temelinizi Konuşalım.
Ali Boran Gazel