API Nedir? Teknik Olmayanlar İçin Rehber

API (Application Programming Interface), iki yazılımın anlaşarak konuşmasını sağlayan arayüzdür. En sevdiğim benzetme restorandır: mutfağa girip kendiniz yemek yapmazsınız, garsona menüden sipariş verirsiniz. Menü API'dir: ne isteyebileceğinizi, nasıl söylemeniz gerektiğini ve karşılığında ne geleceğini tanımlar. Mutfağın içeride nasıl çalıştığı sizi ilgilendirmez, hatta bilmemeniz iyidir; mutfak değişse de menü aynı kaldığı sürece siparişiniz çalışmaya devam eder.

Ürün tarafında çalışan biri için bu, soyut bir bilgisayar konusu değildir. "Ödeme alalım", "haritada gösterelim", "yapay zekâya sorduralım" gibi cümlelerin hepsinin altında bir API vardır.

API nasıl çalışır?

Akış her zaman aynı dört adımdır:

1. İstek (request): Bir yazılım, diğerine belirli bir adresten ve belirli bir biçimde talep gönderir. "Şu kullanıcının son beş siparişini ver."
2. Kimlik doğrulama: Karşı taraf "sen kimsin ve bunu isteme yetkin var mı?" diye bakar. Genelde bir anahtar veya token ile.
3. İşlem: Sunucu talebi işler.
4. Yanıt (response): Sonuç, makinelerin okuyabileceği düzenli bir formatta döner; günümüzde çoğunlukla JSON.

En yaygın tarz REST'tir: her kaynağın (kullanıcı, sipariş, ürün) bir adresi vardır ve üzerinde okuma, oluşturma, güncelleme, silme işlemleri yapılır. Yanında sık duyacağınız iki isim daha var: GraphQL (istemcinin tam olarak istediği alanları tek seferde alması) ve webhook.

Webhook'u ayrıca bilmekte fayda var, çünkü mantığı terstir: siz sormazsınız, olay olunca onlar sizi arar. "Ödeme başarılı oldu" bilgisini öğrenmek için her saniye sormak yerine, ödeme sağlayıcısına adresinizi verirsiniz, olay gerçekleştiğinde size haber gelir. Gerçek zamanlı davranan çoğu entegrasyon böyle çalışır.

Ürün insanı API'yi neden anlamalı?

Çünkü ürününüzün yapabilecekleri, bağlandığınız API'lerin izin verdikleriyle sınırlıdır. Somut sonuçları var:

• Bir özellik mümkün mü, önce API'ye bakılır. "Kullanıcı faturasını uygulama içinden indirsin" fikri, muhasebe sisteminin API'sinde fatura indirme uç noktası yoksa mümkün değildir.
• Veri ne kadar tazedir, API belirler. Webhook varsa anında, yoksa senkronizasyon aralığı kadar gecikmeli.
• Maliyet API'de saklıdır. Özellikle yapay zekâ servislerinde ücret çağrı başına işlenen token miktarıyla hesaplanır; AI maliyetini hesaplama yazısında bunu ayrıntılandırdım.

Kod yazmanız gerekmiyor. Kod yazmadan ürün kurmak yazısında anlattığım gibi, bugün no-code araçların çoğu zaten API'leri birbirine bağlamaktan ibaret; kavramı bilmek aracı kullanmaya yetiyor.

"Bu entegrasyon basit değil mi?" Maliyeti ne belirler?

Ürün toplantılarının klasik cümlesi budur ve neredeyse hep yanılır. Bir entegrasyonun süresini belirleyen şey, mutlu senaryo değil kenar durumlardır:

• Hata halleri: Karşı sistem yanıt vermezse, yarım yanıt verirse, iki kez aynı işlemi kaydederse ne olacak?
• Veri eşleme: Sizdeki "müşteri" ile onlardaki "hesap" aynı şey mi? Zorunlu alanları birbirini tutuyor mu?
• Limitler: Dakikada kaç çağrı hakkınız var?
• Kimlik ve yenileme: Token süresi dolduğunda otomatik yenileniyor mu?
• Sürüm değişikliği: Sağlayıcı API'yi güncellediğinde ne olacak?

Kaba bir kural: bir entegrasyonun mutlu senaryosu işin dörtte biridir. Kalanı, yukarıdaki soruların cevabıdır. Bu yüzden brief yazarken "başarısız olursa ne olsun" sorusunu mutlaka yanıtlayın.

Bilinmesi gereken üç kavram

Rate limit (çağrı sınırı): Servisler dakikada veya günde kaç istek yapabileceğinizi sınırlar. Toplu işlemlerde ("tüm kullanıcılara bildirim gönder") ilk çarpacağınız duvar budur ve genelde test ortamında fark edilmez.

Kimlik doğrulama: API anahtarı en basit yöntemdir; OAuth ise kullanıcının kendi hesabına sizin adınıza erişim vermesidir ("Google ile giriş yap" akışı). İkincisi daha güvenlidir ama kurulumu ve yenilenmesi daha karmaşıktır.

Sürümleme (versioning): İyi API'ler adreslerinde sürüm tutar. Sağlayıcı yeni sürüme geçtiğinde eskisi bir süre daha çalışır. Bu süreye "deprecation" denir ve takip edilmezse bir sabah çalışan entegrasyonunuz durur. Bu, klasik bir teknik borç kaynağıdır.

Sıkça sorulan sorular

API bilmek kod bilmek anlamına mı gelir?

Hayır. Bir API'nin ne sunduğunu, hangi verinin hangi formatta geldiğini ve sınırlarını okumak için kod yazmak gerekmez. Dokümantasyonu okuyabilmek ve doğru soruları sorabilmek ürün tarafı için fazlasıyla yeterlidir.

Entegrasyon neden tahmin edilenden uzun sürüyor?

Çünkü tahminler mutlu senaryoya göre yapılır. Gerçek süre; hata halleri, veri eşleme farkları, çağrı limitleri ve test ortamının gerçek ortamdan farklı davranmasıyla belirlenir. Süreyi ikiye katlamak genelde daha isabetli bir başlangıç tahminidir.

API dokümantasyonunda önce neye bakmalıyım?

Üç şeye: ihtiyacınız olan işlem gerçekten var mı, kimlik doğrulama nasıl yapılıyor, çağrı limiti ne? Bu üçü olumluysa gerisi ayrıntıdır. Bir de örnek yanıtı okuyun; alan isimleri sizin veri modelinizle ne kadar uyuşuyor, oradan anlaşılır.

Üçüncü parti bir API'ye bağımlı olmak riskli mi?

Riskli ama çoğu zaman doğru karar. Kendi çözümünüzü yazmanın maliyeti neredeyse her zaman daha yüksektir. Riski azaltmak için: sağlayıcının kesinti geçmişine bakın, fiyatlandırmanın hacim büyüdüğünde nereye gittiğini hesaplayın ve kritik işlerde servis çalışmadığında ürününüzün nasıl davranacağını önceden tasarlayın.