API Entegrasyonu En İyi Pratikleri

API Entegrasyonu Neden Özen İster?

Modern yazılım projelerinin neredeyse tamamı ödeme altyapıları, e-fatura sağlayıcıları, kargo firmaları, ERP sistemleri veya yapay zekâ servisleri gibi üçüncü taraf API'lerle konuşur. Entegrasyon katmanı çoğu zaman projenin en kırılgan parçasıdır: karşı taraftaki bir gecikme, plansız bir sürüm değişikliği veya yanlış yönetilen bir hata, kullanıcıya doğrudan yansır. Bu rehber, ekibimizin entegrasyon projelerinde uyguladığı ve her API tüketicisine önerdiğimiz temel pratikleri özetler.

1. Kimlik Doğrulamayı Doğru Kurgulayın

Entegrasyonun güvenlik temeli kimlik doğrulamadır. Karşı servisin desteklediği yönteme göre üç yaygın yaklaşım vardır:

API anahtarı: Kurulumu en kolay yöntemdir; ancak anahtar tek başına hem kimlik hem yetki taşıdığı için yalnızca sunucudan sunucuya, TLS üzerinden kullanılmalıdır.
OAuth 2.0 (client credentials): Kurumsal entegrasyonlarda standarttır. Kısa ömürlü erişim belirteci (access token) kullanılır; belirtecin süresi dolmadan yenilenmesi istemci tarafında otomatikleştirilmelidir.
İmzalı istekler (HMAC): Özellikle finansal API'lerde istek gövdesinin gizli anahtarla imzalanması istenir; saat kayması (clock skew) toleransına dikkat edin.

Hangi yöntem kullanılırsa kullanılsın, gizli anahtarlar kod deposuna asla yazılmamalı; ortam değişkenleri veya Vault benzeri bir gizli anahtar yöneticisinde tutulmalı ve düzenli aralıklarla yenilenmelidir.

2. Hata Yönetimini Baştan Tasarlayın

İyi bir entegrasyon, "mutlu yol" kadar hata senaryolarını da planlar. HTTP durum kodlarını doğru yorumlayın:

4xx hataları istemci kaynaklıdır: 400 doğrulama hatası, 401/403 kimlik ve yetki sorunları, 404 yanlış uç nokta, 422 işlenemeyen veri. Bu hatalarda isteği aynen tekrarlamak anlamsızdır; önce neden düzeltilmelidir.
429 hız sınırının aşıldığını gösterir; yanıttaki Retry-After başlığına uyulmalıdır.
5xx hataları sunucu kaynaklıdır ve genellikle geçicidir; kontrollü yeniden deneme adayıdır.

Hata yanıtlarının gövdesini de kaydedin: çoğu sağlayıcı, durum kodunun yanında makine tarafından okunabilir bir hata kodu ve açıklama döndürür. Bu bilgiyi loglamak, destek süreçlerini günlerce kısaltır.

3. Yeniden Denemeyi Akıllıca Yapın

Ağ hataları ve geçici kesintiler kaçınılmazdır; ancak kontrolsüz yeniden deneme, karşı servisi daha da zorlayarak sorunu büyütür. Önerilen yaklaşım:

Üstel geri çekilme (exponential backoff): Denemeler arasındaki süreyi her seferinde katlayarak artırın ve rastgele bir sapma (jitter) ekleyin.
Deneme sınırı: Sonsuz döngüye girmemek için en fazla 3-5 deneme yapın; ardından isteği bir kuyruğa alıp uyarı üretin.
Idempotency anahtarı: Ödeme veya sipariş oluşturma gibi tekrarlanması tehlikeli işlemlerde, sağlayıcı destekliyorsa her isteğe benzersiz bir idempotency anahtarı ekleyin. Böylece aynı işlem yanlışlıkla iki kez gerçekleşmez.
Devre kesici (circuit breaker): Üst üste başarısız olan bir servise istek göndermeyi geçici olarak durdurup sistemin geri kalanını koruyun.

4. Zaman Aşımı ve Eşzamanlılık Sınırları Belirleyin

Zaman aşımı tanımlanmamış bir dış çağrı, uygulamanızın istek havuzunu tüketebilir. Bağlantı ve yanıt için ayrı ayrı, saniyeler mertebesinde makul zaman aşımı değerleri belirleyin. Kullanıcıyı bekleten akışlarda dış servise yapılan çağrıyı mümkünse kuyruk üzerinden asenkron hale getirin; arayüzde ise işlemin sürdüğünü gösteren bir durum sunun.

5. Sürümleme Değişikliklerine Hazırlıklı Olun

API sağlayıcıları zamanla alan ekler, kaldırır veya davranış değiştirir. Entegrasyonunuzu korumak için:

İstek yaptığınız API sürümünü (örneğin /v1/ veya sürüm başlığı) açıkça sabitleyin; "en son sürüm" varsayımıyla çalışmayın.
Yanıtları ayrıştırırken tanımadığınız alanları hata saymayın (tolerant reader yaklaşımı).
Sağlayıcının duyuru ve kullanım ömrü (deprecation) takvimini takip edecek bir sorumluluk tanımlayın.

6. Webhook'ları Güvenli Tüketin

Karşı servisten size gelen bildirimlerde (webhook) iki kural kritiktir:

İmza doğrulaması: Her webhook isteğinin, sağlayıcının paylaştığı gizli anahtarla üretilmiş imzasını doğrulayın; doğrulanamayan istekleri işlemeyin.
Tekrar gönderime dayanıklılık: Sağlayıcılar yanıt alamadıklarında aynı olayı tekrar gönderir. Olay kimliğini kaydederek aynı bildirimi ikinci kez işlemeyi engelleyin ve webhook işleyicisini hızlı yanıt verip işi kuyruğa devredecek şekilde tasarlayın.

7. İzleme ve Loglama Kurun

Entegrasyon "çalışıyor" göründüğü hâlde sessizce bozulabilir. Her dış çağrı için süre, durum kodu ve ilişki kimliği (correlation ID) içeren yapılandırılmış log üretin; başarı oranı ve gecikme metriklerini panoya bağlayın ve eşik aşımında uyarı tanımlayın. Loglarda kişisel veri ve gizli anahtar bulunmamasına özellikle dikkat edin; gerekli alanları maskeleyerek yazın.

8. Test ve Dokümantasyonu İhmal Etmeyin

Sağlayıcının sandbox (deneme) ortamı varsa tüm akışları önce orada doğrulayın. Dış servise yapılan çağrıları tek bir istemci sınıfında toplayıp birim testlerinde sahte (mock) yanıtlarla test edin; kritik akışlar için sözleşme testleri (contract test) ekleyin. Entegrasyonun uç noktalarını, hata senaryolarını ve yapılandırma adımlarını proje dokümantasyonuna işleyin; bu, ekibe katılan her geliştiricinin entegrasyonu güvenle değiştirebilmesini sağlar.

Özet Kontrol Listesi

Gizli anahtarlar kasada, kodda değil; belirteç yenileme otomatik.
4xx/5xx ayrımına uygun hata yönetimi; hata gövdeleri loglanıyor.
Üstel geri çekilme, deneme sınırı ve idempotency anahtarı uygulanıyor.
Tüm dış çağrılarda zaman aşımı tanımlı; kritik akışlar asenkron.
API sürümü sabitlenmiş; bilinmeyen alanlar hata sayılmıyor.
Webhook imzaları doğrulanıyor; yinelenen olaylar ayıklanıyor.
Başarı oranı ve gecikme izleniyor; eşik aşımında uyarı var.
Sandbox ortamında uçtan uca test yapıldı; dokümantasyon güncel.

Mevcut sistemlerinize ödeme, e-fatura, lojistik veya ERP entegrasyonu eklemeyi planlıyorsanız bizimle iletişime geçerek entegrasyon mimarinizi birlikte planlayabiliriz.