API entegrasyonu nasıl planlanır? Hata ve sürüm yönetimi

Bağımlılığın kapsamını çıkarın

Önce hangi işi dış servise devrettiğinizi yazın. Bir fiyat bilgisini göstermekle ödeme sonucunu kaydetmek aynı hata toleransına sahip değildir. Veri kaynağı, gerekli izinler, istek sıklığı, saklanacak alanlar ve servis kesintisinde kullanıcıya sunulacak davranış bir entegrasyon brifinde bulunmalı.

Servisin resmî belgelerini, desteklediği sürümleri ve kullanım koşullarını inceleyin. Eski bir blog örneğinde çalışan uç noktanın bugün hâlâ desteklendiğini varsaymayın. API sahibinin değişiklik ve kullanım dışı bırakma duyurularını izleyecek bir sorumlu belirleyin. Begeni.gen.tr’nin eski havuz yapısı gibi dış servise sıkı bağımlı sistemlerde bu takip eksikliği temel işlevi durdurabilir.

Kimlik doğrulama ve yetkilendirmeyi ayırın

Kimlik doğrulama isteğin kimin adına yapıldığını, yetkilendirme ise hangi işlemlerin yapılabildiğini belirler. API anahtarı, OAuth erişim belirteci veya başka bir mekanizma kullanmanız servise bağlıdır. Gereken en dar izinleri isteyin; yalnızca okuma yapan bir bağlantının yazma iznine ihtiyacı olmamalıdır.

Gizli anahtarları tarayıcıya gönderilen JavaScript’e veya herkese açık depoya koymayın. Sunucu tarafındaki gizli yapılandırmada saklayın, kayıt çıktılarında maskeleyin ve yenileme sürecini planlayın. Kullanıcının şifresini alıp farklı bir serviste oturum açmaya çalışmak yerine, sağlayıcının resmî yetkilendirme akışını kullanın. Yetki iptal edildiğinde bağlantının kapanması anlaşılır bir kullanıcı durumu olmalıdır.

Yanıtları ve hata sınıflarını modelleyin

Bir hata mesajını doğrudan son kullanıcıya veya herkese açık sayfaya basmayın. Yanıt içinde gizli kimlikler, iç sistem bilgileri veya gereksiz teknik ayrıntı bulunabilir. Kullanıcıya ne olduğunu ve hangi adımı atabileceğini açıklayın; teknik ayrıntıyı erişimi kontrollü kayıtlarda tutun.

Zaman aşımı ve tekrar denemeyi sınırlandırın

Her dış isteğin bağlantı ve toplam işlem süresi sınırı olmalı. Sonsuza kadar bekleyen bir istek, uygulama çalışanlarını tüketebilir. Tekrar denemeler gecikmeyi büyütür; bu nedenle azami deneme sayısı ve toplam süre bütçesi belirleyin. Artan bekleme süreleri ve rastgele küçük gecikmeler, aynı anda çok sayıda istemcinin servise yeniden yüklenmesini azaltabilir.

Yazma işlemlerinde “yanıt gelmedi” sonucu “işlem yapılmadı” demek değildir. Sunucu işlemi yapıp yanıtı kaybetmiş olabilir. Ödeme veya sipariş oluşturmada tekrar deneme çift işlem doğurabilir. Sağlayıcının desteklediği idempotency mekanizmasını kullanın veya işlem kimliğini sorgulayarak durumu kesinleştirin. Bu ayrıntı genel bir GET örneğinden kopyalanmamalıdır.

Webhook ve periyodik sorgulama

Webhook, sağlayıcının olay olduğunda size bildirim göndermesidir; periyodik sorgulama ise sizin belirli aralıklarla veri istemenizdir. Webhook kullanıyorsanız sağlayıcının imza doğrulama yöntemini uygulayın, tekrar gönderilen olayları ayırt edin ve olay sırasının garanti edilip edilmediğini belgelerden kontrol edin.

Bildirim alındığında ağır işi doğrudan istek içinde yapmak yerine kuyrukta işlemek uygun olabilir. Ancak önce olayın kalıcı biçimde kaydedildiğinden emin olun. Sağlayıcıya başarılı yanıt verdikten sonra olayı kaybederseniz tekrar gelmeyebilir. Periyodik uzlaştırma işlemi, kaçırılmış olayları yakalamak için ayrıca tasarlanabilir.

Test matrisi hazırlayın

• Geçerli ve süresi dolmuş erişim bilgileri.
• Boş liste, eksik alan ve beklenmeyen veri türü.
• Yavaş yanıt, bağlantı kesilmesi ve hız sınırı.
• Aynı olayın iki kez gelmesi ve olayların ters sırada ulaşması.
• Başarılı yazma sonrası kaybolan yanıt ve tekrar isteği.
• Sürüm değişikliğinde kaldırılan alan veya uç nokta.

Test ortamında gerçek müşteri verisi kullanmak zorunda değilsiniz. Temsili veriyle sözleşme testleri kurun, sağlayıcının deneme ortamını değerlendirin. Canlı kontrolleri ise izin verilen küçük ve geri alınabilir işlemlerle sınırlayın. Test sonuçlarını yalnızca “API çalışıyor” diye özetlemek yerine hangi hata durumlarının ele alındığını belirtin.

İzleme ve çıkış planı

Hata oranı, gecikme, kuyruk uzunluğu ve son başarılı veri zamanı gibi sinyalleri izleyin. Kullanıcı şikâyeti ilk alarm olmamalı. Servis kalıcı olarak kapanırsa hangi verinin dışa aktarılabileceğini, bağlantının nasıl devre dışı bırakılacağını ve arayüzde ne gösterileceğini planlayın. Yedekleme ve mimari seçim kararları bu bağımlılıkları da kapsamalıdır.

Fatura ve cari kayıt bağlantılarında bu ilkeleri ön muhasebe yazılımı demo senaryolarıyla sınayabilirsiniz.