API entegrasyonu, iki sistemi bağlamak değil; güvenilir bir iş akışı tasarlamaktır.

Kısa yanıt: API entegrasyonu nasıl planlanır?

Önce iş olayı, veri sahibi sistem ve başarı ölçütü belirlenir. Kaynak ve hedef alanlar eşlenir; API sözleşmesi, kimlik doğrulama, yetki ve veri minimizasyonu tanımlanır. Zaman aşımı, tekrar deneme, yinelenen işlem, kısmi hata ve geri alma senaryoları tasarlanır. Entegrasyon gerçekçi test verisiyle doğrulanır; canlıda log, metrik, alarm ve mutabakat raporlarıyla izlenir.

• İş olayı ve sistem sorumlulukları
• Veri sözlüğü ve alan eşleme
• API sözleşmesi ve sürüm yönetimi
• Kimlik, yetki ve gizli bilgi yönetimi
• Zaman aşımı, tekrar deneme ve idempotans
• İzleme, alarm ve veri mutabakatı

1. Bağlantıdan önce iş akışını tanımlayın

'CRM ile ERP bağlanacak' ifadesi uygulanabilir bir kapsam değildir. Hangi olayın süreci başlattığı, hangi kaydın oluşturulduğu, kararın hangi sistemde verildiği ve başarılı sonuçta kullanıcının ne gördüğü uçtan uca yazılmalıdır.

Örneğin onaylanan teklifin siparişe dönüşmesi; müşteri, ürün, fiyat, vergi, stok ve ödeme bilgilerinin farklı sahip sistemlerden gelmesini gerektirebilir. Her verinin asıl kaynağı belirlenmeden çift yönlü senkronizasyon veri çakışması üretir.

2. Veri sözlüğü ve eşleme tablosu hazırlayın

Kaynak ve hedef alan adlarının benzemesi, aynı anlamı taşıdıkları anlamına gelmez. Kimlikler, para birimi, saat dilimi, ondalık hassasiyet, zorunlu alan, durum kodu ve silme davranışı açıkça eşlenmelidir.

• Her alanın iş anlamı ve sahibi
• Kaynak–hedef veri tipi ve dönüşüm kuralı
• Zorunlu, koşullu ve varsayılan değerler
• Kimlik eşleme ve tekillik kuralı
• Kişisel verinin aktarım ve saklama sınırı
• Eski kayıtların geçiş ve düzeltme yöntemi

3. API sözleşmesini uygulamadan bağımsızlaştırın

İstek, yanıt, hata, kimlik ve sürüm davranışı kod yazılmadan önce sözleşme hâline getirilmelidir. OpenAPI gibi makinece okunabilir bir tanım; sağlayan ve tüketen ekiplerin aynı arayüzü anlamasına, dokümantasyon ve sözleşme testlerinin otomatikleşmesine yardımcı olur.

Sözleşmede yalnızca başarılı örnek bulunmamalıdır. Doğrulama hatası, yetki reddi, bulunamayan kayıt, kota aşımı ve geçici servis kesintisi ayrı ve tutarlı hata modelleriyle tanımlanmalıdır.

4. Güvenliği her sistem sınırında uygulayın

API anahtarını bir yapılandırma alanına eklemek tek başına güvenlik değildir. Her istemciye gereken en dar yetki verilmeli, gizli bilgiler güvenli kasada tutulmalı, aktarım şifrelenmeli ve nesne düzeyindeki veri erişimi sunucu tarafında doğrulanmalıdır.

OWASP API Security Top 10; nesne düzeyi yetkilendirme, kimlik doğrulama, kaynak tüketimi ve üçüncü taraf API kullanımındaki risklerin özellikle ele alınması gerektiğini vurgular.

• Kısa ömürlü kimlik bilgileri ve anahtar döndürme
• IP veya ağ sınırı gerekiyorsa katmanlı kontrol
• Hassas alanların loglarda maskelenmesi
• İstek başına müşteri ve nesne yetkisi
• Hız sınırı, kota ve kötüye kullanım alarmı

5. Hata ve tekrar davranışını tasarlayın

Ağ bağlantısı yanıt gelmeden kesildiğinde işlemin karşı sistemde tamamlanıp tamamlanmadığı belirsiz olabilir. Kör tekrar; çift sipariş, iki kez ödeme veya yinelenen kayıt oluşturabilir. İşlem anahtarı, idempotans, durum sorgulama ve güvenli tekrar kuralları bu nedenle sözleşmenin parçasıdır.

HTTP semantiğinde idempotans, aynı isteğin birden çok kez uygulanmasının sunucudaki amaçlanan etkisinin tek uygulamayla aynı kalmasıdır. İş akışı POST gerektiriyorsa benzer güvence uygulamaya özgü idempotans anahtarıyla kurulabilir.

• Bağlantı ve işlem zaman aşımını ayırma
• Üstel bekleme ve sınırlı tekrar
• Tekil işlem veya idempotans anahtarı
• Kalıcı hata için kuyruk ve manuel inceleme
• Kısmi başarı için telafi veya geri alma
• Kullanıcıya teknik olmayan durum açıklaması

6. Testi mutlu senaryoyla sınırlamayın

Entegrasyon testi gerçek üretim davranışını temsil etmelidir. Eksik alan, bozuk format, mükerrer mesaj, sıralaması değişen olay, yavaş yanıt, kota sınırı, yetki süresi dolması ve karşı sistem kesintisi kontrollü biçimde denenmelidir.

• Sözleşme ve şema testleri
• Alan dönüşümü ve iş kuralı testleri
• Tekrar, sıra ve eşzamanlılık testleri
• Güvenlik ve yetki sınırı testleri
• Yük, gecikme ve kota testleri
• Uçtan uca iş sonucu ve mutabakat

7. Canlı operasyonu görünür hâle getirin

HTTP 200 oranı tek başına entegrasyonun sağlıklı olduğunu göstermez. İşlemin iş sonucuna ulaşması, veri gecikmesi, hata kuyruğu, tekrar sayısı ve kaynak–hedef kayıt farkı birlikte izlenmelidir.

Her hata için işlem kimliği, kaynak sistem, hedef sistem, aşama ve güvenli hata bağlamı kaydedilir. Alarmın sahibi, müdahale süresi ve manuel tekrar prosedürü canlıya geçmeden belirlenir.

• Teknik başarı ve iş başarısı metrikleri
• Gecikme ve kuyruk derinliği
• Hata sınıfına göre alarm eşikleri
• Günlük veya dönemsel veri mutabakatı
• Tekrar oynatma ve düzeltme araçları
• Sürüm değişikliği ve geriye uyumluluk takibi

Canlıya geçiş kontrolü

Yayın kararı; onaylı veri eşleme, erişim modeli, sözleşme testleri, hata senaryoları, izleme panelleri, mutabakat sonucu ve geri dönüş planı ile verilmelidir. İlk geçiş küçük veri hacmi veya sınırlı kullanıcı grubuyla yapılmalı; eski ve yeni akış belirli süre karşılaştırılmalıdır.