Apı Entegrasyonları Nasıl Yapılır?

API Entegrasyonları Nasıl Yapılır? Uygulamalı Rehber​

API entegrasyonu, iki yazılımın belirli kurallarla veri alışverişi yapmasını sağlar. E-ticaret stok senkronu, hava durumu verisi, ödeme sonucu, CRM kaydı veya kargo takibi gibi işler API'ler sayesinde otomatikleşir.
Başarılı entegrasyon yalnızca endpoint'e istek atmak değildir. Sözleşme, kimlik doğrulama, hata yönetimi, rate limit, retry, loglama, test ve versiyonlama baştan planlanırsa entegrasyon daha güvenilir çalışır.

---

Neden Önemli?​

API entegrasyonları iş süreçlerini hızlandırır; fakat kötü tasarlanırsa veri kaybı, çift kayıt, güvenlik açığı ve kesinti üretir. Özellikle ödeme, stok, üyelik veya kargo gibi alanlarda küçük hata gerçek müşteri deneyimini etkiler.
Bu nedenle entegrasyon projesi, 'dokümantasyondaki örnek kodu çalıştırdım' seviyesinde bırakılmamalıdır. Hangi veri alınacak, hangi sıklıkla çalışacak, hata olursa ne yapılacak ve başarılı işlem nasıl doğrulanacak soruları yazılı hale getirilmelidir.

Sözleşme ve Kapsam​

• Endpoint: Hangi URL, hangi HTTP yöntemi ve hangi parametrelerle çağrılacak netleşir.
• Veri modeli: Alan adları, zorunlu/opsiyonel alanlar, veri tipleri ve örnek yanıtlar belirlenir.
• Başarı kriteri: Hangi durum kodu ve yanıt alanı işlemin başarılı olduğunu gösterir yazılır.
• Hata davranışı: 400, 401, 403, 404, 409, 429 ve 5xx durumlarında ne yapılacağı tanımlanır.
• Sahiplik: API sağlayıcı, tüketici uygulama ve operasyon ekibinin sorumlulukları ayrılır.

Kimlik Doğrulama ve Sır Yönetimi​

API anahtarı, OAuth token veya secret değerleri kod deposuna yazılmamalıdır. Ortam değişkeni, secret kasası veya güvenli yapılandırma alanı kullanılmalıdır. Test ve canlı anahtarlar ayrı tutulmalı; yetki kapsamı en az gerekli seviyede olmalıdır.
Anahtar rotasyonu da planlanmalıdır. Bir anahtar sızarsa hangi sistemlerin etkileneceği, anahtarın nereden iptal edileceği ve yeni anahtarın nasıl dağıtılacağı bilinmelidir. Loglarda token, kimlik bilgisi veya kişisel veri açık şekilde tutulmamalıdır.

İstek, Yanıt ve Hata Yönetimi​

Sağlam entegrasyonda her istek benzersiz takip bilgisiyle loglanır; fakat hassas veri maskelenir. Yanıt gövdesi beklenen şemaya uymuyorsa işlem başarılı kabul edilmez. Sadece HTTP 200 görmek yeterli değildir; dönen verinin anlamı da kontrol edilmelidir.

Pratik not' Alıntı:

Hata mesajını kullanıcıya aynen göstermek yerine, kullanıcı diline çevrilmiş kısa açıklama ve ekip için teknik referans id kullanın.

Genişletmek için tıkla ...

Zaman aşımı değerleri de gerçekçi olmalıdır. Sonsuza kadar bekleyen istek uygulamayı kilitleyebilir; çok kısa timeout ise yoğun saatlerde gereksiz hata üretebilir.

Rate Limit, Retry ve Idempotency​

API sağlayıcılarının çoğu belirli süre içinde yapılabilecek istek sayısını sınırlar. 429 yanıtı alındığında kör tekrar denemek yerine bekleme süresi, exponential backoff ve kuyruk mantığı kullanılmalıdır.
POST gibi durum değiştiren işlemlerde retry daha dikkatli tasarlanır. Aynı sipariş, ödeme veya kayıt ikinci kez oluşmamalıdır. Sağlayıcı destekliyorsa idempotency key veya benzersiz işlem anahtarı kullanılmalı; desteklemiyorsa uygulama tarafında tekrar kontrolü yapılmalıdır.

Test ve Gözlemleme​

• Happy path yanında başarısız kimlik doğrulama, eksik alan, rate limit, timeout ve 5xx senaryoları test edilir.
• Test verisi canlı müşteri verisiyle karıştırılmaz.
• Webhook veya callback gelmediğinde tekrar sorgulama planı bulunur.
• Başarı oranı, hata oranı, gecikme, kuyruk birikimi ve son başarılı senkron zamanı izlenir.
• Kritik entegrasyonlarda alarm eşiği ve sorumlu ekip önceden belirlenir.

Versiyonlama ve OpenAPI​

API değişiklikleri entegrasyonları kırabilir. Bu yüzden endpoint versiyonu, geriye uyumluluk ve kaldırılacak alanların tarihi takip edilmelidir. OpenAPI gibi sözleşme formatları, hem insan hem araçlar için API davranışını daha anlaşılır hale getirir.
Küçük projede bile örnek istek/yanıt dosyaları, hata kodu tablosu ve değişiklik günlüğü tutulmalıdır. Entegrasyon bir kez yazılıp unutulmaz; sağlayıcı dokümanı ve uygulama ihtiyacı değiştikçe güncellenir.

Mikro Vaka​

Bir mağaza kargo API'sine siparişleri gönderirken timeout yaşadığında aynı siparişi tekrar tekrar oluşturuyordu. Sipariş id'siyle idempotent kontrol eklendi, timeout sonrası önce gönderi durumu sorgulandı ve hata alarmı kuruldu. Çift kargo kaydı sona erdi.

Basit Formül​

SSS​

• API entegrasyonuna nereden başlanır? Kullanım amacı, veri modeli, endpoint listesi ve başarı kriteri yazılarak başlanır.
• API anahtarı nerede saklanmalı? Kod deposunda değil; ortam değişkeni veya secret yönetiminde saklanmalıdır.
• Postman yeterli mi? Test için faydalıdır; fakat üretim kodunda timeout, retry, log ve güvenlik ayrıca uygulanmalıdır.
• Rate limit aşılırsa ne yapılır? Bekleme, kuyruk ve backoff stratejisi kullanılmalıdır.
• Webhook güvenli mi? İmza doğrulaması, gizli token ve tekrar teslim kontrolü varsa daha güvenlidir.
• Başarı nasıl ölçülür? Hata oranı, gecikme, son başarılı işlem, veri tutarlılığı ve kullanıcıya etkisi birlikte izlenir.

Entegrasyon Tasarım Dokümanı​

Küçük bir API işi için bile kısa tasarım dokümanı hazırlanmalıdır. Bu dokümanda amaç, veri kaynağı, endpoint listesi, kimlik yöntemi, örnek istek/yanıt, hata kodları, tekrar deneme kuralı, rate limit ve gözlemleme metrikleri yer alır. Doküman uzun olmak zorunda değildir; ancak entegrasyonu devralan bir geliştirici ilk gün neyin neden yapıldığını anlayabilmelidir.
Tasarım dokümanı aynı zamanda iş ekibiyle teknik ekip arasındaki sözleşmedir. 'Stok güncellenecek' demek yerine 'her 15 dakikada değişen stoklar çekilecek, başarısız işlem kuyrukta kalacak, son başarılı senkron zamanı panelde görünecek' gibi net ifade kullanılır.
Bu netlik kapsam kaymasını da azaltır. Yeni alan, yeni sağlayıcı veya yeni rapor isteği geldiğinde ekip mevcut sözleşmeye bakıp bunun küçük değişiklik mi yoksa ayrı entegrasyon işi mi olduğunu daha kolay ayırır.

Webhook Entegrasyonlarında Dikkat Edilecekler​

Webhook, sağlayıcının sizin sisteminize olay bildirmesidir; ödeme alındı, kargo çıktı veya abonelik yenilendi gibi olaylarda kullanılır. Webhook uçları herkese açık URL olduğu için imza doğrulaması, secret kontrolü, tekrar teslim yönetimi ve hızlı yanıt verme disiplini gerekir.

• Webhook imzası doğrulanmadan işlem yapılmamalıdır.
• Aynı event ikinci kez gelirse işlem tekrar uygulanmamalıdır.
• Webhook içinde uzun iş yapılmamalı; iş kuyruğa alınıp hızlı 2xx yanıt dönülmelidir.
• Başarısız event'ler izlenmeli ve tekrar işleme alınabilmelidir.

Geliştirici Kontrol Listesi​

• Timeout değeri ve retry sayısı bilinçli seçildi mi?
• API anahtarı kod deposu dışında mı tutuluyor?
• Hata yanıtları kullanıcıya sade, loglara teknik detayla mı yazılıyor?
• Rate limit aşımında kuyruk veya bekleme uygulanıyor mu?
• Testler hem başarılı hem başarısız senaryoları kapsıyor mu?
• Versiyon değişikliği veya deprecated alanlar takip ediliyor mu?

Bu liste her entegrasyon canlıya alınmadan önce tekrar çalıştırılırsa tekrar eden hatalar azalır. Özellikle ödeme ve stok gibi ticari etkisi yüksek API'lerde bu kontrol canlı sorunları ciddi ölçüde düşürür.
Kontrol listesinin çıktısı görev yönetiminde saklanmalıdır. Böylece altı ay sonra entegrasyon değiştiğinde hangi varsayımların geçerli olduğu, hangi limitlerin ölçüldüğü ve hangi hataların bilinçli kabul edildiği görülebilir.

İç Bağlantılar​

• OpenWeatherMap API entegrasyonu
• REST Countries API entegrasyonu
• Ücretsiz API kaynakları
• Programatik SEO ve veri entegrasyonu

Dış Kaynak​

• MDN: HTTP
• OpenAPI Specification
• Stripe Docs: idempotent requests

Özetle​

API entegrasyonu, endpoint çağırmanın ötesinde sözleşme, güvenlik, hata yönetimi ve gözlemleme disiplinidir. Test ve canlı ortamı ayırın; retry ve rate limit davranışını baştan tasarlayın.

Güncelleme: 2026-06-16

---