API nedir? Sistemler birbiriyle nasıl konuşur?
API (Uygulama Programlama Arayüzü), bir yazılımın başka bir yazılıma sunduğu kurallı kapıdır: ne isteyebileceğiniz, nasıl isteyeceğiniz ve ne alacağınız önceden tanımlıdır. Web'de en yaygın biçimi, adreslere istek gönderip JSON yanıt alan REST API'lerdir; ters yönde çalışan webhook'lar ise olay olduğunda sizi arar. Entegrasyonun değeri, insanın iki ekran arasında veri taşımasını ortadan kaldırmasıdır.
- API, sistemler arasındaki sözleşmedir
- REST istek gönderir, webhook olay olduğunda haber verir
- Anahtarlar sunucuda saklanır, tarayıcıda değil
- Entegrasyonun maliyeti, karşı tarafın dokümantasyonuyla doğru orantılıdır
API nedir?
API (Application Programming Interface / uygulama programlama arayüzü), bir yazılımın başka yazılımlarla konuşmak için açtığı kurallı bir kapıdır. İnsana yönelik arayüz ekrandır; makineye yönelik arayüz API'dir. Vikipedi'nin tanımıyla API, bir bileşenin sunduğu hizmetleri ve bu hizmetlerin nasıl çağrılacağını belirleyen bir arayüz tanımıdır.
Somut örnek: kargo firmasının API'si "bana gönderi numarası ver, sana durumu döneyim" der. Muhasebe programının API'si "bana fatura bilgisi gönder, ben keseyim" der. Bu kapılar olmasaydı, birinin her sabah iki ekranı açıp veriyi elle taşıması gerekirdi.
REST, JSON ve webhook
Web dünyasında en yaygın yaklaşım REST'tir: her kaynak bir adrestir ve o adrese GET, POST, PUT, DELETE gibi yöntemlerle istek gönderilir. Yanıt genellikle JSON biçiminde döner. Bir API'nin ne sunduğunu makinelerin de okuyabileceği biçimde yazmak için OpenAPI tanımı kullanılır; iyi bir API'nin OpenAPI dokümanı vardır.
Webhook ters yönde çalışır. Siz sormazsınız; olay olduğunda karşı taraf sizin adresinizi çağırır. "Ödeme alındı", "kargo teslim edildi", "form dolduruldu" gibi olaylar için webhook, sürekli sorgulamaktan çok daha verimlidir.
Entegrasyon ne işe yarar?
- Elle veri taşımayı bitirir. Sipariş e-postadan tabloya, tablodan muhasebeye kendiliğinden geçer.
- Hata payını düşürür. Kopyala-yapıştır hataları ve unutulan kayıtlar ortadan kalkar.
- Gecikmeyi kısaltır. Ay sonunda öğrenilen bilgi, olduğu anda öğrenilir.
- Tek gerçeklik kaynağı kurar. "Hangi listedeki rakam doğru?" tartışması biter.
API güvenliği: en sık yapılan üç hata
- Anahtarı tarayıcıya koymak. API anahtarı sunucuda durur. Tarayıcıya yazılan anahtar, kaynak koda bakan herkes tarafından görülür.
- Yetki kontrolünü unutmak. Kullanıcı kendi verisini görebilmeli, adresteki numarayı değiştirince başkasının verisini değil. OWASP'ın 2025 listesinde bozuk erişim kontrolü hâlâ bir numaralı risktir.
- Sınır koymamak. Hız sınırı (rate limit) olmayan bir API, bir hatalı döngüyle kendi sunucunuzu düşürebilir.
Entegrasyon projesinde sorulacak sorular
Bir entegrasyonun maliyetini teknoloji değil, karşı tarafın düzeni belirler. Başlamadan önce şunları netleştirin:
- Dokümantasyon güncel mi, test ortamı (sandbox) var mı?
- Hız sınırı nedir, hata durumunda ne dönüyor?
- Veri günlük mü, anlık mı akacak? Webhook desteği var mı?
- Karşı taraf API'yi değiştirirse nasıl haber veriyor (sürümleme)?
- Kişisel veri geçiyorsa hangi alanlar zorunlu; gereksiz alan göndermemek mümkün mü?
İyi bir entegrasyon, iki sistemin birbirine benzemesini gerektirmez; yalnızca aralarındaki sözleşmenin net olmasını gerektirir.
Kaynaklar
- Vikipedi, Uygulama programlama arayüzü
- OpenAPI Initiative, OpenAPI Specification
- OWASP, OWASP Top 10:2025
Sık sorulan sorular
Her yazılımın API'si var mı?
Hayır. Özellikle eski ya da yerel kurulan programların API'si olmayabilir; bu durumda veritabanına doğrudan bağlanmak ya da dosya aktarımı gibi yöntemler kullanılır.
Entegrasyon ne kadar sürer?
Dokümantasyonu iyi, test ortamı olan bir servisle birkaç gün; belgesiz ve destek vermeyen bir sistemle haftalar sürebilir.
API kullanmak ücretli mi?
Değişir. Birçok servis belirli bir istek sayısına kadar ücretsizdir, sonrasında kullanım başına ücretlendirir.
Webhook mu, düzenli sorgulama mı?
Mümkünse webhook. Sürekli sorgulama hem gereksiz yük oluşturur hem de bilgiyi geç getirir.
