API, webhook ve kuyruk: entegrasyon mimarisi

Sistem entegrasyonu denince akla genellikle tek bir şey gelir: API. Oysa iki sistemi bağlamanın birbirinden farklı üç temel yolu vardır ve hangisinin kullanılacağı, projenin dayanıklılığını doğrudan belirler. Üçünü karıştırmak ya da birini her yerde kullanmaya çalışmak, entegrasyonların en sık kırılma sebebidir.

API: ben sorarım, sen cevaplarsın

API, bir sistemin dışarıya açtığı çağrı noktasıdır. Siz istek gönderirsiniz, karşı taraf cevap döner. Bu modelin adı istek-cevaptır ve en büyük avantajı basitliğidir: cevabı hemen alırsınız, sonucu anında kullanıcıya gösterebilirsiniz.

Dezavantajı da buradan gelir. Cevap gelmezse ne olacağı tanımlanmak zorundadır. Karşı sistem yavaşsa kullanıcı bekler; kapalıysa işlem başarısız olur. Bu yüzden API çağrılarında üç şey mutlaka tanımlanır: zaman aşımı süresi, kaç kez yeniden deneneceği ve denemeler arasında ne kadar bekleneceği.

Yeniden deneme aralığı sabit olmamalıdır. Karşı sistem zaten zorlanıyorken saniyede bir istek göndermek durumu kötüleştirir. Doğru yaklaşım, her denemede bekleme süresini artırmaktır: bir saniye, iki, dört, sekiz. Karşı sistem "çok fazla istek" anlamına gelen bir yanıt dönüyorsa, bu yanıtın içinde bildirdiği bekleme süresine uyulmalıdır.

Webhook: sen haber verirsin

Webhook, yönün tersine çevrilmiş hâlidir. Siz sormazsınız; karşı sistemde bir şey olduğunda size bildirim gönderilir. Ödeme sonucu, kargo durumu değişikliği ve pazaryeri sipariş bildirimi tipik örneklerdir.

Webhook'un avantajı, boşuna yapılan sorgulamayı ortadan kaldırmasıdır. Günde on bin gönderiyi saatte bir sorgulamak yerine, yalnızca durumu değişenler için bildirim alırsınız.

Üç kuralı vardır. Birincisi doğrulama: gelen bildirimin gerçekten o sistemden geldiği imza kontrolüyle doğrulanmalıdır, aksi hâlde adresi bilen herkes sahte bildirim gönderebilir. İkincisi hız: bildirim alındığı anda uzun bir işlem başlatılmamalı, bildirim kaydedilip hemen başarı yanıtı dönülmelidir; geç cevap veren adresler çoğu sistemde devre dışı bırakılır. Üçüncüsü tekrar: aynı bildirim birden fazla kez gelebilir, bu yüzden her bildirimin kimliği saklanmalı ve tekrarı işlenmemelidir.

Kuyruk: arada bir tampon

Kuyruk, iki sistem arasına konan bir bekleme alanıdır. Gönderen taraf mesajı kuyruğa bırakır ve işine devam eder; alıcı taraf kuyruğu kendi hızında boşaltır.

Bu yapının kazandırdığı şey dayanıklılıktır. Karşı sistem kapalıyken mesajlar kuyrukta bekler, sistem açıldığında işlenir ve hiçbir şey kaybolmaz. Ani yük artışlarında da aynı tampon işe yarar: bin sipariş aynı anda gelse bile karşı sistem onları sırayla işler, altında ezilmez.

Bedeli gecikmedir. Kuyruğa atılan bir işin ne zaman tamamlanacağı garanti edilmez, bu yüzden kullanıcıya anında sonuç gösterilmesi gereken yerlerde kuyruk tek başına yeterli değildir. Pratikte en sağlam kurgu ikisinin birleşimidir: kullanıcıya "işleminiz alındı" denir, iş kuyruğa atılır, tamamlandığında bildirim gönderilir.

Hangi durumda hangisi

Seçimi belirleyen soru şudur: sonucu kim, ne zaman bekliyor? Kullanıcı ekranın başında sonucu bekliyorsa API gerekir. Karşı sistemde bir şey olduğunda haberdar olmanız gerekiyorsa webhook gerekir. İşin tamamlanması saniyeler sürebilir ve kullanıcı beklemek zorunda değilse kuyruk gerekir.

Gerçek projelerde üçü birden kullanılır. Bir e-ticaret siparişinde ödeme sonucu webhook ile gelir, stok düşümü API ile anında yapılır, muhasebeye aktarım ve e-posta gönderimi kuyruğa atılır. Hepsini API ile yapmaya çalışmak, tek bir yavaş sistemin tüm sipariş akışını durdurması anlamına gelir.

Her entegrasyonun iz kaydı olmalı

Hangi yöntem kullanılırsa kullanılsın, giden ve gelen her mesaj kaydedilmelidir: ne zaman, hangi adrese, hangi içerikle gidildi ve ne cevap geldi. Bu kayıt olmadan "sipariş niye aktarılmamış?" sorusunun cevabı bulunamaz.

Kayıtta kart numarası, parola ve kişisel veri gibi hassas alanlar maskelenmelidir. İz kaydının kendisi bir güvenlik açığına dönüşmemelidir. Saklama süresi de belirlenmeli; sınırsız büyüyen bir iz tablosu bir süre sonra veri tabanının en büyük tablosu hâline gelir ve sorguları yavaşlatır.

Sürüm değişikliğine hazırlık

Karşı sistemin arayüzü er geç değişir. Buna hazırlıklı olmanın yolu, dış sisteme giden kodu uygulamanın geri kalanından ayırmaktır. Sipariş akışı doğrudan kargo firmasının adresini çağırmaz; kendi içindeki "gönderi oluştur" fonksiyonunu çağırır, o fonksiyon karşı sistemi bilir.

Bu ayrım sayesinde arayüz değiştiğinde yalnızca tek bir dosya güncellenir. Dış sistemin alan adlarının uygulamanın her yerine yayıldığı projelerde ise aynı değişiklik onlarca dosyaya dokunmayı ve baştan test etmeyi gerektirir.