Açıkça, güvenle ve nadiren hata veren API’ler ve entegrasyonlar.
Sözleşme öncelikli API’ler, olay tabanlı entegrasyon ve kurumları tutarlı tutan o gösterişsiz disiplin — idempotency, yeniden denemeler, dead-letter kuyrukları.
- Sistem haritası
- Sözleşmeler
- Geliştirme ve gölge
- Devreye geçiş ve izleme
Karşı tarafın çöktüğü gün için tasarlanır.
Her kurum, aslında iş modeli giymiş bir entegrasyon problemidir. ERP, CRM, ödeme altyapıları, iş ortağı beslemeleri — değer, birleşme noktalarındadır. API’leri sözleşme, entegrasyonları ise hata davranışı açıkça tanımlanmış olay akışları olarak tasarlıyoruz; çünkü kötü bir salı gününde sistem bütününün ayakta kalıp kalmayacağını belirleyen kısım burasıdır.
En sık karşılaştığımız tablo, eksik bir entegrasyon değildir. Yıllar içinde birkaç ekibin yazdığı çok sayıda entegrasyondur; her birinin kendi yeniden deneme mantığı, müşteri kimliğinin ne olduğuna dair kendi tanımı ve o an bir şeyin akıp akmadığına dair ortak bir görünümün yokluğu vardır. Gece çalışan dosyalar boşlukları örter; bir mutabakat tablosu da dosyaları örter. Bizim işimiz, bunun yerine az sayıda yönetişimi tanımlı sözleşme, olguların bir log üzerinde durduğu bir olay omurgası ve bozulan bir akışın ay sonu sürprizi değil hızlı bir uyarı olmasını sağlayacak kadar gözlemlenebilirlik koymaktır.
Bir entegrasyonun sınavı mutlu senaryo değildir — karşı taraf çöktüğünde, yavaşladığında ya da aynı mesajı iki kez gönderdiğinde ne olduğudur.
Dört disiplin, bu sırayla uygulanır.
Önce sözleşmeler; çünkü beyaz tahtada değiştirmesi ucuz, birçok tüketici sistemde değiştirmesi pahalıdır. Hata davranışı ise en son unutulması gereken şeydir; çünkü sonunda birlikte yaşadığınız şey odur.
Sözleşme öncelikli API tasarımı
Koddan önce OpenAPI tanımları. Sürümleme, sayfalama ve hata anlamları, değiştirmesi hâlâ ucuzken karara bağlanır. Sözleşmeyi onu kullanacak ekiplerle birlikte yazar, sunucu iskeletlerini ve istemci SDK’larını ondan üretir, uyumluluk kurallarını CI içinde zorunlu kılarız; böylece kırıcı bir değişiklik bir iş ortağının entegrasyonunu değil derlemeyi düşürür.
Olay tabanlı omurgalar
Outbox deseniyle Kafka / kuyruk tabanlı entegrasyon — çift yazma yarışı yok, sessiz kayıp yok. Olay, iş değişikliğiyle aynı veritabanı işleminde yazılır ve bir connector ya da Debezium tarafından aktarılır; böylece bir üretici bir olguyu kaydedip bildirimini kaybedemez. Tüketiciler idempotenttir, bir iş kimliğiyle anahtarlanır ve offset’i ancak etki kalıcı olduktan sonra işler.
Legacy ve SaaS bağlantısı
SOAP önyüzleme, dosya bırakma ile veri alma, webhook normalizasyonu — sistemlerle gerçekte bulundukları yerde buluşuruz. Kimsenin değiştiremeyeceği bir mainframe, change data capture ile bir olay kaynağına dönüşür; bir FTP dizini doğrulanmış, yeniden oynatılabilir bir beslemeye dönüşür. Sarmalayıcının arkasında kendi hızımızda modernize eder, tüketiciler farkı hiç görmez.
Hata mühendisliği
Idempotency anahtarları, yeniden deneme bütçeleri, dead-letter kuyrukları ve yeniden oynatma araçları — ilk olaydan sonra eklenmez, baştan tasarlanır. Teslim ettiğimiz her akışın dört soruya yazılı bir yanıtı vardır: hedef çöktüğünde, yavaşladığında, hata döndürdüğünde ve aynı mesaj iki kez geldiğinde ne olur. O yanıt varsayılmaz, test edilir.
İş günlük olarak nasıl yürür?
Çıktı kod değil, sözleşmedir.
Tüketicileri şartnameyi okumadan yayına çıkan bir API, canlı ortamda ve seyirci önünde yeniden tasarlanır. Biz bunu tersine çeviriyoruz. Önce OpenAPI ya da AsyncAPI dokümanı yazılır ve onu kullanacak her ekiple gözden geçirilir — kaynak şekilleri, sayfalama, idempotency başlıkları, hata kodları, hız sınırları ve kullanımdan kaldırma politikası. Uygulama ancak sözleşme bu incelemeden geçtikten sonra başlar ve istemci SDK’larıyla mock sunucunun da üretildiği aynı dokümandan üretilir. Tüketiciler, sözleşme imzalandığında mock üzerinde geliştirmeye başlayabilir; bu da plandan sıra bekleme süresini çıkarır.
- Sürüm kontrolü altında OpenAPI 3.1 ve AsyncAPI dokümanları, diğer her değişiklik gibi pull request olarak incelenir
- CI içinde uyumluluk kontrolleriyle eklemeli değişiklik politikası — kırıcı bir alan silme işlemi CI hattını düşürür
- Kullanım telemetrisiyle desteklenen kullanımdan kaldırma pencereleri; v1’i kapatmadan önce kimin hâlâ çağırdığını görebilirsiniz
Karanlığa çağrı değil, log üzerinde olgular.
İki sistem arasındaki senkron bir çağrı, ikisinin çalışma süresini, işlem hacmini ve sürüm takvimini birbirine bağlar. Etkileşim aslında birkaç sistemin bilmesi gereken bir olguysa — sipariş verildi, sevkiyat açıldı, ödeme geçti — bunu kalıcı ve sıralı bir log’a bir kez yayınlar, her tüketicinin kendi hızında okumasına izin veririz. Yavaş bir sistem herkesin problemi olmaktan çıkar, bir kesinti kayıp değil birikmiş iş hâline gelir ve alt sistemdeki bir tabloyu bozan bir hata, veriyi yeniden girerek değil bir zaman aralığını yeniden oynatarak düzeltilir. Üretici tarafı outbox desenini kullanır; böylece olgu ve olayı tek bir commit’i paylaşır.
- Topic sahipliği, anahtarlar, şemalar ve saklama süreleri, depoda duran bir olay kataloğunda kayıtlıdır
- Bir registry’de tutulan ve CI’da uyumluluk kuralları uygulanan şemalar — Avro, Protobuf ya da JSON Schema
- Kaynağın değiştirilemediği yerlerde Oracle, SQL Server, MySQL ya da PostgreSQL üzerinden change data capture
Hata davranışı, önceden kararlaştırılır.
Entegrasyonlar genellikle bir exception ile bozulmaz. Bir tarafta zaman aşımı, diğer tarafta işlenmiş bir yazma ile bozulur; ya da bir iş ortağının dünkü dosyayı yeniden göndermesiyle, ya da yavaş bir bağımlılığı büsbütün ölü hâle getiren bir yeniden deneme fırtınasıyla. Hata politikasını her akış için koddan önce yazarız: ne, kaç kez yeniden denenir, ne geri çekilir, ne bekletilir, ne dead-letter kuyruğuna gider, kim çağrılır ve yeniden oynatma prosedürü nedir. Politika, bir incelemede okuyabileceğiniz bir tablodur ve saat 03:00’te keşfedilmek yerine devreye geçişten önce hata enjeksiyonuyla test edilir.
- Bir iş kimliğine anahtarlanmış idempotency; en az bir kez teslimat, tam olarak bir kez sonuç üretir
- Üstel geri çekilme ve devre kesicilerle yeniden deneme bütçeleri; yavaş bir bağımlılık kesintiye dönüştürülemez
- Provası yapılmış yeniden oynatma prosedürüne sahip dead-letter kuyrukları ve yalnızca hatalarda değil dead-letter hacminde de uyarı
Önce gölge, sonra devreye geçiş.
Bir entegrasyon programının en riskli saati, yeni bir akışın kayıt sistemine yazmaya başladığı saattir. Biz o saati ortadan kaldırıyoruz. Yeni entegrasyonlar gerçek canlı trafiğe karşı gölge modda çalışır — aynı girdileri tüketir, aynı çıktıları üretir, hiçbir yere yazmaz — bu sırada bir karşılaştırıcı yeni sonuç ile mevcut sonuç arasındaki her farkı raporlar. Farklar, geriye kalanlar açıklanabilir ve üzerinde mutabık kalınmış hâle gelene kadar azaltılır. Akış ancak o zaman, genelde önce tek bir segment için, eski yol hâlâ sıcakken ve provası yapılmış bir geri alma hazırken yazmaya başlar.
- Farkları türe ve hacme göre raporlayan bir karşılaştırıcı; birinin göz kararı baktığı bir örneklem değil
- Segment, iş ortağı ya da bölge bazında devreye geçiş; her adım geri alınabilir
- Fark raporu üzerinde anlaşılan süre boyunca temiz kalana kadar legacy yol çalışmaya devam eder
Bir entegrasyonu üç kişi, üç ayrı nedenle önemser.
Yönetişimi kurulmuş tek bir bütün ve gerçeğe uyan bir resim.
Gerçeği yansıtan bir envanter alırsınız: her akış, sahibi, sözleşmesi, tutarlılık gereksinimi ve hata politikası. Yeni bağlantılar da aynı incelemeden geçer; böylece biz ayrıldıktan sonra sistem bütünü yeniden parçalanmaz. Doğru yanıt daha iyi entegrasyonlar değil daha az entegrasyonsa bunu söyleriz — yalnızca iki ekip sahiplik konusunda anlaşamadığı için var olan noktadan noktaya bir akış, mühendislik değil yönetişim problemidir.
- Veri sahipleri ve tutarlılık gereksinimleriyle sistem ve akış envanteri
- REST, GraphQL ve olaylar için standartlar — ve aralarında seçim yapma kuralı
- Gateway politikası: kimlik doğrulama, hız sınırları, anahtarlar, kotalar ve doküman portalı
Bir panodan haberdar olursunuz, müşteriden değil.
Teslim ettiğimiz her akış kendi görünümüyle gelir: işlem hacmi, gecikme, hata oranı, dead-letter derinliği ve işlenmemiş en eski mesajın yaşı. Uyarı politikaları akışın yanında kod olarak tutulur; böylece yeni bir entegrasyon bunlar olmadan canlı ortama çıkamaz. Her hata modunun runbook’unu akışı kuran mühendisler yazar ve canlıya çıkıştan önce ekibinizle bir game day’de prova edilir.
- Akış başına panolar ve uyarı politikaları, kodla birlikte sürümlenir
- Hata modu başına runbook’lar; dosyalanmak yerine prova edilir
- Nöbetçi ekibinizin bizsiz çalıştırabileceği yeniden oynatma ve mutabakat araçları
İş ortağının görüşme yapmadan katılabileceği bir API.
Dış API’ler, destek maliyeti olan bir üründür. Gateway katmanını geliştirici deneyimiyle birlikte kurarız: self servis anahtarlar, sandbox kimlik bilgileri, üretilmiş referans dokümantasyonu, kod örnekleri ve neyin değiştiğini, eski davranışın ne zaman biteceğini söyleyen bir changelog. Hız sınırları ve kotalar tüketici bazındadır; böylece hevesli bir iş ortağı diğerlerinin performansını düşüremez ve kullanım telemetrisi hangi uçların bakım maliyetini gerçekten hak ettiğini gösterir.
- Self servis katılım: anahtarlar, sandbox, üretilmiş dokümanlar ve örnekler
- Tüketici bazında hız sınırları, kotalar ve kullanım telemetrisi
- Takvime bağlı, çağrı verisiyle desteklenen sürümleme ve kullanımdan kaldırma duyuruları
Her çalışmada olanlar ve her sistem bütününe göre şekillenenler.
Dört faz; gölge modda çalışmayan hiçbir şey yazmaz.
Sistem haritası
Sistemlerin, veri sahiplerinin ve akışların envanteri — ve her bağlantının gerçekte hangi tutarlılığı gerektirdiği. Hangi bağlantıların güçlü tutarlılık gerektirdiğini, hangilerinin saniyeler içinde nihai tutarlılıkla yetinebileceğini ve hangilerinin yıllardır kimse şikâyet etmeden gecelik çalıştığını çıkarırız. Bu yanıt mimariyi belirler ve genelde varsayılandan daha ucuza çıkar.
Sözleşmeler
Uygulama başlamadan önce OpenAPI / olay şemaları, kullanacak her ekiple gözden geçirilir. Her sözleşme kendi hata anlamlarını, idempotency kurallarını, saklama süresini ve sahipliğini taşır. Mock sunucular ve üretilmiş SDK’lar imzalanan sözleşmeyle birlikte çıkar; böylece tüketici ekipler bizi beklemek yerine bizimle paralel geliştirir.
Geliştirme ve gölge
Entegrasyonlar canlı trafiğe karşı gölge modda çalışır; hiçbir şey devreye geçmeden önce çıktılar karşılaştırılır. Hata enjeksiyonu hata politikasının tamamını kapsar — hedef çökmüş, hedef yavaş, yinelenen teslimat, bozuk payload — ve bir tarih üzerinde anlaşılmadan önce karşılaştırma raporu açıklanamayan fark kalmayana kadar çalışılır.
Devreye geçiş ve izleme
Akış başına panolar, gecikme ve hata oranlarında uyarılar ve belgelenmiş yeniden oynatma prosedürleriyle kademeli devreye geçiş. Eski yol sıcakken her seferinde tek bir segment taşırız, ardından nöbetçi ekibinizle bir game day’de runbook’ları devrederiz. Hiçbir şey devreye alındığı için bitmiş sayılmaz; ekibiniz kurtarmayı bir kez çalıştırdığında biter.
Sonunda elinizde olanlar.
- Sürüm kontrolü altında OpenAPI / AsyncAPI sözleşmeleri
- İzleme panolarıyla birlikte devreye alınmış entegrasyon akışları
- Idempotency, yeniden deneme ve dead-letter politikaları — belgelenmiş ve test edilmiş
- Yeniden oynatma ve mutabakat araçları
- Tasarımda ele aldığımız her hata modu için runbook’lar
- Sahipleri, anahtarları, şemaları ve saklama süreleriyle bir olay ve uç kataloğu
- Kod olarak altyapı ve uyarı politikaları, akışlarla aynı depolarda
Bunun doğru karar olduğu durumlar.
Birkaç sistemden fazlası aynı olgular üzerinde anlaşmak zorundaysa, bir bağlantı para ya da bir mevzuat yükümlülüğü taşıyorsa veya mevcut sistem bütünü sahipleri çoktan ayrılmış noktadan noktaya betiklerden oluşuyorsa bunu seçin. Bir modernizasyon ya da legacy yeniden mühendislik programından önce de doğru karardır: yönetişimi kurulmuş bir entegrasyon katmanı, her tüketiciyle yeniden pazarlık etmeden bir kayıt sistemini değiştirmenizi sağlayan şeydir. İş ortaklarına açılan API’ler bir ürüne dönüşüyorsa ve bunun getirdiği katılım, sürümleme ve destek gerekiyorsa yine doğru karardır.
Bir ürün ekibinin uçtan uca sahiplenebileceği, iki sistem arasındaki tek bir bağlantı için doğru karar değildir — o bir program değil bir sprinttir ve bunu size söyleriz. Biz ayrıldıktan sonra sözleşmeleri, şemaları ve tüketici gecikmesini kimse sahiplenmeyecekse doğru karar değildir; sahipsiz bir entegrasyon katmanı, veri kaybetmek için son derece kalıcı bir yere dönüşür. Asıl sorun müşteri kaydının kime ait olduğu konusunda iki departmanın anlaşamaması ise hiçbir mühendislik bunu çözmez — önce o konuşmanın yapılması gerekir.
Sık sorulan sorular
Bu hizmetin genellikle konumlandığı yer.
Ne geliştirdiğinizi anlatın.
Bugün elinizde ne olduğunu ve neye ihtiyacınız olduğunu anlatın. Bir mühendis okur ve nasıl yaklaşacağımızı yazılı olarak iletir.