API entegrasyon tasarımı: sistemleri güvenilir biçimde nasıl bağlarsınız?
Sağlam entegrasyon yalnız iki API arasında veri taşımak değildir. Veri sahipliği, durum eşleme, idempotency, retry ve reconciliation sınırları sistemlerin zaman içinde tutarlı kalmasını belirler.
Önce veri sahipliğini tanımlayın
Bir entegrasyon projesinde ilk refleks çoğu zaman hangi endpoint'in çağrılacağını belirlemektir. Daha kritik soru ise hangi sistemin hangi gerçeğin sahibi olduğudur. Müşteri, ödeme, rezervasyon veya içerik kaydının ana durumu iki farklı sistemde aynı anda bağımsız biçimde değişebiliyorsa senkronizasyon problemi kaçınılmaz hale gelir.
Bu nedenle entegrasyon sözleşmesi veri akışından önce sahipliği tanımlamalıdır. Harici sistem kendi uzmanlık alanındaki gerçeği üretirken, uygulamanın domain modeli işletmenin ihtiyaç duyduğu ilişki ve operasyon durumlarını kendi doğruluk kaynağında tutabilir.
Harici durumları domain modeline açıkça eşleyin
İki ürün aynı kavram için farklı durumlar, kimlikler ve yaşam döngüleri kullanabilir. Harici bir sağlayıcının durumunu uygulamanın iç durumuna doğrudan kopyalamak, sağlayıcının modelini zamanla kendi iş kurallarınıza sızdırır.
Daha dayanıklı yaklaşım, çeviriyi açık bir mapping katmanında yapmaktır. Hangi harici durumun hangi iç duruma karşılık geldiği, bilinmeyen bir değer geldiğinde ne olacağı ve iki taraftaki kimliklerin nasıl ilişkilendirildiği test edilebilir bir sözleşmeye dönüşür.
- Harici ve iç kimlik eşlemesi
- Durum ve enum dönüşümleri
- Zorunlu / opsiyonel alan sınırları
- Bilinmeyen veya yeni durum davranışı
- Versiyon ve geriye uyumluluk kararı
Retry ile idempotency birlikte tasarlanmalıdır
Ağ bağlantısı kesilebilir, karşı servis geçici olarak hata verebilir veya yanıt istemciye ulaşmadan işlem karşı tarafta tamamlanmış olabilir. Bu nedenle retry mekanizması entegrasyonların doğal parçasıdır. Fakat aynı isteğin ikinci kez çalışması ikinci bir ödeme, rezervasyon veya kayıt üretebiliyorsa retry yeni bir hata kaynağına dönüşür.
İdempotent işlem tasarımı aynı niyetin tekrar gönderilmesini güvenli hale getirir. Benzersiz işlem anahtarı, harici referans veya kontrollü upsert gibi yöntemler; retry politikasının domain davranışıyla birlikte düşünülmesini sağlar.
Başarısızlık görünür ve uzlaştırılabilir olmalıdır
Entegrasyon hatasını yalnız log satırı olarak bırakmak operasyon ekibinin gerçeği anlamasını zorlaştırır. Hangi işlem başarısız oldu, en son ne zaman denendi, harici sistem hangi cevabı verdi ve tekrar denemek güvenli mi gibi bilgiler gözlemlenebilir olmalıdır.
Bazı hatalar otomatik retry ile kapanır; bazıları mapping veya yetki problemi nedeniyle insan kararı ister. Reconciliation ise iki tarafın mevcut durumunu yeniden okuyup farkı doğrulayarak 'işlem gerçekten yapılmadı mı, yoksa sadece yanıt mı kayboldu?' sorusunu çözmeye yardım eder.