API entegrasyonu: hata yönetimi ve teslim kontrol listesi

Bağımlılığı baştan görünür yapın

Entegrasyon kurulacak servisin hangi veriyi okuyup hangi işlemi yazacağını listeleyin. Gerekli erişim düzeyi, test ortamı ve güncel kullanım koşullarını resmi dokümantasyondan doğrulayın. Erişimin sürmesi veya limitlerin değişmemesi garanti değildir.

Takipci.gen.tr’nin geçmiş havuz deneyimi, dış servise bağımlı bir işlevin çalışmadığında sitenin değerini kaybedebileceğini gösteriyor. İş planında API kesilirse kullanıcının hangi bilgiyi göreceğini ve hangi işlemlerin duracağını tanımlayın.

Başarısız istekleri sınıflandırın

Geçersiz veri ile geçici servis hatası aynı şekilde ele alınmamalıdır. Doğrulama hatasında kullanıcıdan girdiyi düzeltmesini isteyin. Geçici ağ hatasında sınırlı tekrar deneme düşünülebilir. Oran sınırında sağlayıcının bekleme talimatını ve güncel dokümantasyonunu izleyin.

Her isteğe zaman aşımı koyun. Sınırsız tekrar deneme hem maliyeti artırır hem karşı servisi zorlar. Ödeme veya sipariş oluşturma gibi işlemlerde tekrarın iki kez kayıt üretmemesi için servis destekliyorsa idempotency anahtarı veya uygulama düzeyinde eşdeğer bir kontrol kullanın.

Webhook bildirimlerini doğrulayın

Webhook, bir olay gerçekleştiğinde karşı sistemin sizin adresinize bildirim göndermesidir. Gelen isteğin kaynağını sağlayıcının imza doğrulama yöntemine göre denetleyin. İşlemi güvenli biçimde kaydedip uzun işleri kuyrukta yürütmek, yanıtın gecikmesini önleyebilir.

GitHub’ın webhook önerileri HTTPS, gizli anahtar, olay türü kontrolü ve teslim kimliğiyle tekrarların ayırt edilmesi gibi noktaları ele alır. Diğer servislerde başlık isimleri ve süreler farklı olabilir; örneği evrensel protokol gibi kopyalamayın. Aynı olay iki kez geldiğinde iş mantığınızın ne yapacağını test edin.

Yayın öncesi hata senaryolarını sınayın

• Yetki reddi ve süresi dolmuş erişim bilgisi.
• Boş, eksik veya beklenmeyen yanıt.
• Oran sınırı ve geçici kesinti.
• Tekrarlanan veya sırası değişen bildirimler.
• Uzun süren istek ve kısmen tamamlanan işlem.

Kayıtlarda erişim anahtarı, parola veya gereksiz kişisel veri tutmayın. İzleme için işlem kimliği, hata sınıfı ve süre gibi yeterli alanları seçin. Kullanıcıya teknik yığın izi yerine ne yapabileceğini anlatan bir hata mesajı gösterin. Teslimde kabul ölçütlerine bu senaryoları ekleyin.

Kullanıcıya kısmi başarıyı doğru gösterin

Bir uygulamada kayıt oluşturulmuş fakat dış servise bildirim gönderilememiş olabilir. Kullanıcıya bütün işlem başarısızmış gibi mesaj vermek aynı işlemi yeniden başlatmasına ve çift kayıt oluşmasına yol açabilir. Yerel kayıt ile dış sistemdeki aktarımın durumunu ayrı izleyin.

Örnek bir durum dizisi “kaydedildi”, “aktarım bekliyor”, “aktarıldı” ve “inceleme gerekiyor” olabilir. Bunlar uygulama tasarımı örnekleridir; iş akışınıza göre uyarlayın. Yeniden denemeyi kimin başlatabildiğini ve önceki girişimin sonucunun nasıl doğrulanacağını tanımlayın.

Uzlaştırma işleminde iki sistemdeki kayıtları ortak bir işlem kimliği üzerinden karşılaştırın. Eksik kaydı tekrar göndermeden önce karşı tarafta zaten oluşup oluşmadığını kontrol edin. Teknik hata kaydı ile kullanıcıya gösterilen açıklamayı ayırın; ekran mesajında erişim anahtarı veya iç sistem ayrıntısı göstermeyin.