API entegrasyonu: hata yönetimi ve teslim kontrol listesi
API ile bağlı çalışan uygulamalarda yetki, zaman aşımı, oran sınırı, webhook, tekrar deneme ve izleme gereksinimlerini planlayın.
Bir API entegrasyonu yalnızca başarılı istek senaryosundan oluşmaz. Yetki süresi dolduğunda, servis yanıt vermediğinde ve aynı bildirim tekrar geldiğinde ne olacağını da tasarlayın.
Bu rehberde neler var?
- Bağımlılığı baştan görünür yapın
- Başarısız istekleri sınıflandırın
- Karar tablosu: durumunuzu değerlendirin
- Webhook bildirimlerini doğrulayın
- Yayın öncesi hata senaryolarını sınayın
- Başarılı ödeme, geciken sipariş bildirimi
- Kullanıcıya kısmi başarıyı doğru gösterin
- Uygulama kontrolü ve dikkat edilecek nokta
- Sık sorulan sorular
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.
Karar tablosu: durumunuzu değerlendirin
Dar ekranda tüm sütunları görmek için tabloyu yatay kaydırabilirsiniz.
| Durum | Nasıl yorumlanır? | Sonraki adım |
|---|---|---|
| Kesin ret | Yetki veya alan doğrulaması gibi açık hata dönüyor. | Nedeni düzeltmeden aynı isteği sürekli göndermeyin; kullanıcıya anlamlı durum gösterin. |
| Geçici erişim sorunu | Servis veya ağ kısa süreli yanıt vermiyor. | Kontrollü tekrar ve artan bekleme kullanın; sınırları sağlayıcının belgelerine göre belirleyin. |
| Belirsiz sonuç | İstek zaman aşımına uğradı, işlem gerçekleşmiş olabilir. | Yeniden oluşturma öncesinde durum sorgusu ve işlem eşleştirmesi yapı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.
Başarılı ödeme, geciken sipariş bildirimi
AÇIKLAMALI ÖRNEK · TEMSİLÎ SENARYO
Bir ödeme alınmış fakat sipariş sistemine bildirim ulaşmamış olsun. Kullanıcıya yeniden ödeme yaptırmak sorunu büyütebilir. Uygulama önce kendi işlem kaydıyla sağlayıcının durumunu ilişkilendirir; sonuç kesin değilse “işleniyor” gibi doğru bir durum gösterir. Destek ekibinin hangi işlem kimliğini araştıracağı belirli olmalıdır.
Bildirim daha sonra tekrar geldiğinde aynı sipariş ikinci kez oluşturulmamalıdır. Olay kimliği veya işleme özgü bir anahtar saklanarak tekrarlar ayırt edilir. Testte ağ kesilmesi, geç bildirim ve aynı bildirimin birden çok gelişi ayrı senaryolar olarak çalıştırılır. Bu örnek belirli bir ödeme sağlayıcısının protokolü değildir; gerçek entegrasyonun doğrulama ve tekrar kuralları kendi belgelerinden uygulanmalıdır.
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.
Uygulama kontrolü ve dikkat edilecek nokta
KENDİ ÇALIŞMANIZA UYGULAYIN
- Gizli anahtarların URL, tarayıcı kodu ve uygulama günlüklerine yazılmadığını kontrol edin.
- Webhook kaynağını sağlayıcının önerdiği doğrulama yöntemiyle kontrol edin.
- Başarısız ve belirsiz işlemleri destek ekibinin görebileceği bir takip düzenine bağlayın.
Sık sorulan sorular
API çalışıyorsa entegrasyon tamamlanmış sayılır mı?
Başarılı istek yeterli değildir. Yetki, kesinti, tekrar deneme, izleme ve veri tutarlılığı senaryoları da sınanmalıdır.
Webhook gelmezse ne yapılmalı?
Sağlayıcının teslim kayıtları ve yeniden gönderim olanakları incelenmeli; kritik işlerde eksik olayları uzlaştıracak bir süreç tasarlanmalıdır.
Entegrasyon sadece başarılı istekle test edilebilir mi?
Hayır. Tekrar, geç bildirim, yetki hatası, eksik veri ve servis kesintisi de denenmelidir. Gerçek operasyon yükünün önemli bölümü bu durumların kullanıcıya ve destek ekibine doğru yansıtılmasıdır.
Kaynaklar ve doğrulama
Bu kaynaklar ilgili platform veya teknik konu için referanstır. Örnek senaryolar editoryal açıklamalardır; bağımsız ürün testi veya gerçek müşteri sonucu değildir. Değişebilen koşulları işlem öncesinde resmi kaynaktan doğrulayın.
Bu rehber Takipci.gen.tr tarafından hazırlanmıştır. Temsilî senaryolar ve hesaplamalar yöntemi açıklamak içindir; ölçülmüş müşteri sonucu veya başarı garantisi değildir. Yayın ve kaynak yaklaşımımız.