Klasik web API'lerinde istemci bir istek gönderir, sunucu işi yapar ve sonucu aynı bağlantı üzerinden döner. Bu model, birkaç yüz milisaniye süren işlemler için idealdir. Ancak bir kasko sorgusu birden fazla sigorta şirketine istek göndermeyi, her birinin yanıtını beklemeyi ve sonuçları birleştirmeyi gerektirdiğinde işlem süresi uzar ve öngörülemez hale gelir. Bu tür işlemleri senkron bir HTTP isteğine sığdırmaya çalışmak; zaman aşımlarına, yarıda kalan bağlantılara ve kötü bir kullanıcı deneyimine yol açar. Asenkron API tasarımı, uzun süren işlemleri istek-yanıt döngüsünden ayırarak bu sorunları çözer.
Senkron modelin kırıldığı nokta
Bir HTTP isteğinin yolunda yük dengeleyiciler, ters vekil sunucular ve mobil ağ geçitleri bulunur. Bu katmanların her birinin kendi zaman aşımı ayarı vardır. Sunucu işini bitirmiş olsa bile aradaki bir katman bağlantıyı daha önce kesmiş olabilir. Kullanıcı hata görür, oysa işlem arka planda tamamlanmıştır. Kullanıcı tekrar dener ve aynı sorgu iki kez çalışır. Ayrıca mobil cihazlarda uygulama arka plana alındığında açık bağlantılar işletim sistemi tarafından kesilebilir. Uzun bir senkron istek, mobil dünyada her zaman kırılgandır.
Temel desen: Kabul et, kimlik ver, sonra bildir
Asenkron modelde istemci işlemi başlatan isteği gönderir. Sunucu isteği doğrular, bir iş kaydı oluşturur ve işi arka plana devreder. Yanıt olarak hemen bir iş kimliği ve işin durumunu sorgulamak için kullanılacak adresi döner. HTTP dünyasında bu durum için uygun yanıt kodu "202 Accepted" yani kabul edildi kodudur. Bu kod, isteğin alındığını ama işlemin henüz tamamlanmadığını açıkça ifade eder.
Bu yanıtın gövdesinde şu bilgilerin bulunması önerilir:
- İş kimliği
- Durum sorgulama adresi
- İşin mevcut durumu, örneğin "kuyrukta"
- İstemcinin ne sıklıkla durum sorgulaması gerektiğine dair bir öneri
Durum uç noktası tasarımı
Durum uç noktası, işin yaşam döngüsünü anlaşılır biçimde yansıtmalıdır. Çoklu şirket sorgularında tek bir genel durum yetmez; her şirket için ayrı durum bilgisi de gerekir. İyi tasarlanmış bir durum yanıtı şunları içerir:
- Genel durum: Kuyrukta, işleniyor, kısmen tamamlandı, tamamlandı veya başarısız.
- Şirket bazlı durumlar: Her hedef şirket için bekleniyor, yanıt geldi, hata veya zaman aşımı.
- Gelen sonuçlar: Tamamlanan şirketlerin teklif bilgileri.
- Zaman bilgileri: İşin başlangıç zamanı ve son güncelleme zamanı.
"Kısmen tamamlandı" durumu özellikle önemlidir. Bazı şirketlerden yanıt gelmişken diğerleri hâlâ bekleniyorsa, kullanıcı elindeki sonuçlarla çalışmaya başlayabilmelidir. Trafik, kasko ve DASK sorgularının sonuç yapıları farklı olduğundan durum yanıtındaki sonuç nesnesi de branşa özel şemaya sahip olmalıdır.
Sonuçları istemciye ulaştırmanın üç yolu
Kısa aralıklı sorgulama
İstemci belirli aralıklarla durum uç noktasını çağırır. En basit ve en dayanıklı yöntemdir; her istek bağımsızdır, bağlantı kopsa bile bir sonraki sorguda kaldığı yerden devam edilir. Dezavantajı, gereksiz isteklerin sunucuya yük bindirmesi ve sonuçların sorgulama aralığı kadar gecikmeyle görünmesidir. Aralığın sabit değil, işlemin ilerleyişine göre uyarlanan bir yapıda olması bu dezavantajı hafifletir.
Sunucu tarafından gönderilen olaylar
İstemci tek bir uzun ömürlü bağlantı açar ve sunucu her yeni gelişmede bu bağlantı üzerinden bir olay gönderir. Sonuçlar oluştuğu anda istemciye ulaşır. Tarayıcılar bu yöntemi yerel olarak destekler ve bağlantı koptuğunda otomatik yeniden bağlanma sağlar. Son alınan olay kimliği sayesinde yeniden bağlanan istemci kaçırdığı olayları alabilir.
Satır satır JSON akışı
Sunucu, yanıtı tek bir büyük JSON yerine her satırı ayrı bir JSON nesnesi olan bir akış olarak gönderir. Her şirketin sonucu geldiğinde yeni bir satır yazılır. Bu yöntem mobil istemcilerde de kolayca uygulanabilir ve sonuçların kademeli olarak ekrana gelmesini sağlar. Ancak bağlantı koptuğunda akışın nereden devam edeceği istemci tarafında yönetilmeli; bu durumda durum uç noktasına geri dönülerek eksik sonuçlar tamamlanmalıdır.
Pratikte bu yöntemler birbirinin alternatifi değil tamamlayıcısıdır. Akış veya sunucu olayları ana kanal olarak kullanılırken durum uç noktası her zaman güvenilir bir yedek olarak kalmalıdır.
İptal ve zaman aşımı
Kullanıcı sonuçları beklerken ekranı kapatabilir veya sorguyu değiştirmek isteyebilir. Asenkron API, işi iptal etmek için bir yol sunmalıdır. İptal isteği geldiğinde henüz gönderilmemiş şirket çağrıları durdurulur, devam edenlerin sonuçları ise kayda alınır ama kullanıcıya sunulmaz. Ayrıca her işin sunucu tarafında bir üst süre sınırı olmalıdır. Bu süre aşıldığında yanıt vermeyen şirketler zaman aşımı olarak işaretlenir ve iş tamamlanmış sayılır. Sonsuza kadar "işleniyor" durumunda kalan işler hem kullanıcıyı hem sistemi yorar.
Sonuçların saklanması ve erişim güvenliği
İş sonuçları belirli bir süre saklanmalıdır ki kullanıcı ekranı yenilediğinde veya başka bir cihazdan baktığında sonuçlara yeniden ulaşabilsin. İş kimlikleri tahmin edilemez olmalı ve durum uç noktası, isteği yapan kullanıcının o işe erişim yetkisi olup olmadığını her seferinde kontrol etmelidir. Aksi halde bir acentenin sorgu sonuçları, kimliği tahmin eden başka bir kullanıcı tarafından görüntülenebilir.
Mükerrer başlatmayı önlemek
Asenkron modelde de işi başlatan istek ağ sorunları nedeniyle tekrarlanabilir. Başlatma isteğinin idempotency anahtarı taşıması ve aynı anahtarla gelen ikinci isteğe yeni bir iş açmak yerine mevcut işin kimliğini dönmesi gerekir. Bu sayede kullanıcı ne kadar tekrar denerse denesin tek bir sorgu yürür.
Webhook ile geri bildirim seçeneği
İstemci bir sunucu ise, örneğin acentenin kendi iç sistemi veya bir iş ortağı uygulaması, durum sorgulamak yerine iş tamamlandığında bir webhook ile bilgilendirilmeyi tercih edebilir. Bu durumda işi başlatan istek, sonucun gönderileceği adresi de içerir. Webhook bildirimi imzalı olmalı, yalnızca iş kimliğini ve özet durumu taşımalı; ayrıntılı sonuçlar ise yetkili bir istekle durum uç noktasından alınmalıdır. Böylece hassas teklif verisi gereğinden fazla sisteme dağılmaz.
InsureHub'da asenkron motor
InsureHub, sigorta acentelerine yazılım sağlarken uzun süren teklif işlemlerini sürümlü motor API'leri üzerinden asenkron olarak yürütür. Sigorta teklif programı ekranında şirket sonuçlarının geldikçe listelenmesi ve mobil sigorta uygulaması tarafında satır satır akan sonuçlar, bu tasarımın kullanıcıya dokunan yüzüdür.