API entegrasyonu nedir?
API entegrasyonu; iki veya daha fazla sistemin veri ve iş akışını standart bir arayüz üzerinden güvenli biçimde paylaşmasıdır. Örneğin e‑ticaret siparişi oluştuğunda; stok, ödeme, kargo, fatura ve bildirim süreçleri farklı sistemlerde yürüyebilir. Entegrasyonun amacı, bu parçaları tek bir operasyon gibi çalıştırmaktır.
REST API mantığı (kısa)
REST; kaynak odaklı bir modeldir. Sipariş, müşteri, ürün gibi kaynaklar standart HTTP metodlarıyla yönetilir. Kurumsal tarafta önemli olan; tutarlı isimlendirme, doğru hata kodları ve idempotent davranışlardır.
| Metod | Ne yapar? | Not |
|---|---|---|
| GET | Veri okur | Yan etkisiz olmalı |
| POST | Kayıt oluşturur | Tekrarlı çağrıda dikkat |
| PUT | Kayıdı bütünüyle günceller | İdeal olarak idempotent |
| PATCH | Kısmi güncelleme | Alan bazlı değişim |
| DELETE | Siler | Soft delete tercih edilebilir |
Webhook ve event akışı (grafik)
Webhook; bir olay olduğunda (ödeme başarılı, kargo durum değişti, iade oluşturuldu) sistemin karşı tarafa otomatik bildirim göndermesidir. En önemli nokta; güvenlik ve tekrar denemelerdir. Webhook her zaman “birden fazla kez gelebilir” varsayımıyla işlenmelidir.
Senkron vs asenkron entegrasyon
Senkron entegrasyon; bir istek atıp aynı anda cevap beklemektir. Asenkron entegrasyon; işin kuyruğa alınması veya webhook ile olay bazlı ilerlemesidir. Kurumsal senaryolarda asenkron yaklaşım stabiliteyi artırır.
- Senkron: kullanıcı anında sonucu görmeli (ör. adres doğrulama)
- Asenkron: uzun süren iş, dış servis bağımlılığı, tekrar deneme ihtiyacı (ör. kargo barkod oluşturma)
Güvenlik: API key, OAuth, imzalama
Entegrasyonlarda güvenlik; sadece “anahtar koymak” değildir. Yetkilendirme, veri maskeleme, rate limit ve kayıt/izleme birlikte ele alınır.
- API key: servis‑servis erişiminde kullanılır; mümkünse IP kısıtı ve rate limit ile
- OAuth: kullanıcı yetkisi gerektiğinde; scope ve token ömrü yönetimiyle
- İmzalama: webhook doğrulama için HMAC imzası ve timestamp kontrolü
- Least privilege: gereğinden fazla yetki verilmez
Kurumsal yaklaşım: her entegrasyon için erişim kapsamı, anahtar rotasyonu ve denetim logu standardı tanımlanır.
Hata yönetimi ve idempotency
Hata yönetimi; entegrasyonun “gerçek” kalitesidir. Dış servis hataları, zaman aşımları ve tekrarlı istekler mutlaka olacak. Bu yüzden iki kavram kritik:
- Retry: geçici hatalarda kontrollü tekrar deneme (backoff ile)
- Idempotency: aynı istek iki kez gelirse sonuç bir kez oluşmalı
Örneğin ödeme “başarılı” webhook’u iki kez gelirse, sipariş iki kez “ödendi” olmamalı. Çözüm; event id, idempotency key veya benzersiz işlem kimliği ile “tekil işleme” sağlamaktır.
Rate limit ve performans
Rate limit, sistemin korunmasıdır. Kurumsal projelerde limitler; sadece saldırıyı değil, yanlış yazılmış entegrasyonları da kontrol altına alır. İstemci tarafında “429 Too Many Requests” durumunda bekle‑devam et mantığı olmalıdır.
- Limit politikası: istemci bazlı, endpoint bazlı veya token bazlı
- Cache: sık okunan kaynaklar (örn. ürün listesi) için
- Pagination: büyük listelerde zorunlu
Versiyonlama ve geriye uyumluluk (grafik)
API değişir. Önemli olan değişimi “kırmadan” yönetmektir. Geriye uyumsuz bir değişiklik yapıyorsanız, yeni sürüm çıkarmak doğru yaklaşımdır.
Log, izleme ve denetlenebilirlik
Kurumsal entegrasyonlarda “neden olmadı?” sorusuna cevap verebilmek gerekir. Bu yüzden loglar ve izleme metrikleri proje kapsamının parçasıdır.
- Correlation id: isteği uçtan uca takip etmek
- Audit log: kritik aksiyonların kaydı (kim, ne, ne zaman)
- Dashboard: başarı/başarısız webhook sayısı, gecikme, hata türleri
- Alarm: hata oranı artarsa uyarı
Kurumsal entegrasyon checklist
- Endpoint’ler ve veri sözleşmesi (request/response) net mi?
- Auth modeli (API key / OAuth) ve anahtar rotasyonu tanımlı mı?
- Rate limit, pagination ve cache stratejisi var mı?
- Retry/backoff ve idempotency kurgusu hazır mı?
- Webhook doğrulama (HMAC + timestamp) uygulanıyor mu?
- Log/izleme, dashboard ve alarm kuruldu mu?
- Versiyonlama ve deprecate planı tanımlı mı?
Sık sorulan sorular
API entegrasyonu nedir?
API entegrasyonu; iki sistemin veri ve iş akışını API üzerinden güvenli ve tutarlı biçimde haberleştirmesidir.
Webhook nedir, API’den farkı ne?
Webhook; bir olay olduğunda sistemin karşı tarafa otomatik bildirim göndermesidir. API çağrısı ise genellikle veriyi isteme/çekme için kullanılır.
OAuth mı, API key mi kullanılmalı?
Kullanıcı yetkisi gereken senaryolarda OAuth daha uygundur. Basit servis‑servis erişiminde API key yeterli olabilir; yine de rate limit ve imzalama önerilir.
API versiyonlama nasıl yapılır?
Geriye dönük uyumsuz değişikliklerde yeni sürüm çıkarılır. Eski sürüm bir süre daha desteklenir; geçiş planı ve kapanış tarihi paylaşılır.
Kurumsal entegrasyon için teklif alabilir miyim?
Entegrasyon kapsamı (hangi sistemler, hangi olaylar, hangi veri sözleşmesi) netleşince plan ve teklif kalemleri görünür olur. Detaylı görüşme için iletişime geçebilirsiniz.