API Rehberi: bağlan, kullan, faturayı anla — Atlas

KAZANIM Bu dersin sonunda: ilk API çağrını kendi ellerinle yapmış olur, istek/cevap anatomisini okur, ücretsiz API hazinesini tanır ve herhangi bir API'nin sana kaça mal olacağını ÖNCEDEN hesaplarsın.

Bu dosyanın rolü: DERİNLİK — API kavramının (kavramlar-seviye-3) uygulamalı hâli. Secret disiplini 2.6'da, MCP bağlantısı 3.4'te.

📅 Son tarama: 9 Temmuz 2026. Bu rehberdeki örnek API'ler o gün canlı test edildi; fiyat örnekleri o günün resmî listelerinden.

---

Bölüm 1 · API'yi bir kez daha, elle tutulur hâliyle

API = bir servisin dış dünyaya açtığı sipariş penceresi. Sen (ya da senin ürünün) pencereye standart formatta bir istek verirsin, servis standart formatta cevap döner. Bütün modern yazılım dünyası bu pencerelerin birbirine bağlanmasıdır: ürünün ödemeyi PayTR'nin penceresinden, e-postayı Resend'in penceresinden, zekâyı Claude'un penceresinden alır.

İki tür pencere var: anahtarsız (herkese açık — kimlik sormaz) ve anahtarlı (API key ister — kim olduğunu ve faturayı kime keseceğini bilmek için). Anahtarsızla öğrenilir, anahtarlıyla iş yapılır.

Bölüm 2 · İlk API çağrın — 60 saniye, kayıt yok, kart yok

Tarayıcında yeni sekme aç ve adres çubuğuna şunu yapıştır:

https://dog.ceo/api/breeds/image/random

Gördüğün şey bir API cevabıdır (JSON):

{
  "message": "https://images.dog.ceo/breeds/husky/n02110185_1469.jpg",
  "status": "success"
}

Satır satır: message = asıl mal (rastgele bir köpek fotoğrafının adresi — aç, bak) · status = "isteğin başarılı" mührü. Tebrikler — az önce bir sunucuya istek attın, yapılandırılmış veri aldın. Ürünündeki her AI çağrısı, her ödeme, her e-posta bu mekanizmanın süslenmiş hâlidir.

Kodda aynı şey (JavaScript, diller.md üslubuyla satır satır):

const cevap = await fetch("https://dog.ceo/api/breeds/image/random"); // pencereye git
const veri = await cevap.json();   // cevabı JSON olarak aç
console.log(veri.message);         // zarfın içinden malı çıkar

İkinci adım — parametreli istek (Open-Meteo, hava durumu; yine anahtarsız):

https://api.open-meteo.com/v1/forecast?latitude=41.01&longitude=28.97&current_weather=true

?'den sonrası query parametreleri — siparişin ayrıntıları: "İstanbul koordinatları, şu anki hava." Cevapta current_weather.temperature gelir. Parametreyi değiştir (Ankara: 39.93, 32.86) → cevap değişir. API kullanmanın özü budur: adres + parametre → yapılandırılmış cevap.

Bölüm 3 · Anahtarlı API'ler: anahtar → .env → çağrı

Gerçek iş API'leri (Claude, PayTR, Resend...) anahtar ister. Akış hep aynı:

1. Anahtarı al: sağlayıcının sitesinde hesap → "API Keys" sayfası → oluştur → BİR kez gösterilir, kopyala.
2. .env dosyasına koy (2.6'nın demir kuralı): ANAHTAR_ADI=sk-abc123... — koda, sohbete, commit'e ASLA yazılmaz. .gitignore'da .env satırının varlığını denetle.
3. Çağrıda kullan: anahtar istekte Authorization başlığıyla gider. Ajanına şöyle dersin: ".env'deki CLAUDE_API_KEY ile bir çağrı kur" — içeriğini sen bile görmezsin, görmemelisin.
4. Sızarsa protokol (2.6 rotasyon): anahtarı sağlayıcı panelinden İPTAL et → yenisini üret → .env'i güncelle → sızıntının nereye kadar gittiğini denetle (git geçmişi dahil). "Belki fark eden olmaz" bir strateji değildir.

Bölüm 4 · Faturayı anla: 3 fiyat modeli

Token-başı fiyatın okunuşu: "$3/$15 per 1M" = milyon girdi-token'ı $3, milyon çıktı-token'ı $15. Kabaca 1 token ≈ TR'de yarım kelime. Fiyat makası devasa: aynı özet işi DeepSeek Flash'ta ($0.28/M çıktı) ile en pahalı frontier modelde yüzlerce kat fark eder — model seçimi bütçe kararıdır (llm-haritasi Bölüm 8 + 4.4).

İki tuzak: (1) "Ücretsiz katman" bazen kredi kartı ister — "unutursan öderiz" modelidir; kartsız ücretsiz katmanla başla, kartlıysa harcama limitini/uyarısını İLK GÜN kur. (2) Çıktı token'ı girdiden 3-6× pahalıdır — "kısa cevap ver" istemi gerçek para tasarrufudur.

Bölüm 5 · Ücretsiz API hazinesi: github'daki public-apis

GitHub'ın en yıldızlı depolarından biri (github.com/public-apis/public-apis, ~450 bin yıldız): 1.400+ ücretsiz API'nin kategorili kataloğu — hava durumu, döviz, haber, spor, yemek, oyun... Tablonun okunuşu:

• Auth sütunu: No = anahtarsız (öğrenme dostu) · apiKey = ücretsiz anahtar al · OAuth = kullanıcı-izinli giriş (ileri seviye).
• HTTPS/CORS sütunları: Yes olanları seç (tarayıcıdan çağrılabilirlik).

Üç mini-proje fikri (hepsi anahtarsız, hepsi Claude Code'a tek istemle yaptırılır):

1. Hava durumu widget'ı — Open-Meteo: "şehrimin şu anki havasını gösteren tek sayfalık widget yap."
2. Döviz çevirici — Frankfurter (Avrupa Merkez Bankası kurları): api.frankfurter.dev/v1/latest?base=EUR&symbols=TRY → "EUR/USD/TRY çevirici yap."
3. Rastgele-bilgi kartı — Dog CEO ya da REST Countries: "her yenilemede rastgele bir ülke kartı göster: bayrak, başkent, nüfus."

Bölüm 6 · Rate limit ve kota: pencerenin kuralları

Her API "dakikada en çok N istek / ayda en çok M çağrı" sınırı koyar (rate limit). Aşarsan cevap 429 Too Many Requests olur — hata değil, "yavaşla" sinyali. Ürünün için anlamı: (1) kullanıcı başına istek sınırla; (2) aynı soruya aynı cevabı tekrar tekrar satın alma — önbelleğe al (cache); (3) sağlayıcı panelindeki kullanım grafiğine ayda bir bak. LLM API'lerinde ek kavram: dakikadaki TOKEN limiti — uzun dokümanlı işlerde istekten önce hesapla.

Denetim penceresi

Her API entegrasyonundan sonra üç soru: (1) Bu çağrı bana kaça mal oluyor? (birim fiyat × aylık tahmini hacim — rakamı söyleyemiyorsan denetim bitmemiştir) · (2) Limitim ne, dolunca ne olur? (sessizce kesilir mi, fatura mı kabarır?) · (3) Anahtar nerede yaşıyor? (.env'de mi, koda/git'e sızmış mı — git log -p | grep -i key tarzı bir taramayı ajanına yaptır). Kırmızı bayraklar: kartlı "ücretsiz" katman + limit uyarısı kurulmamış · anahtarın commit geçmişinde görünmesi · faturanın hangi çağrıdan şiştiğini bilememek.

Mini egzersiz (SANDBOX)

Bölüm 5'teki üç mini-projeden birini seç ve Claude Code'a yaptır. Sonra denetim penceresini uygula: ajana "bu API'nin rate limit'i ne, aşarsak kullanıcı ne görür, aylık maliyeti kaç?" sorularını sor. (Cevap "sıfır TL, anahtarsız" olsa bile hesabı GÖSTERMESİNİ iste — alışkanlık maliyetli API'ye geçince hazır olsun.)

Kontrol soruları

(1) Anahtarsız ve anahtarlı API'nin farkı ve her birinin yeri nedir? (2) Query parametresi ne işe yarar — Open-Meteo örneğinde hangileriydi? (3) "$1/$5 per 1M token" ne demek, çıktı neden pahalı? (4) Anahtar sızdı: dört adım nedir? (5) 429 cevabı ne söyler, ürününde nasıl karşılarsın?

Mentor istemi

AI Maestro "API Rehberi" hocası ol. Önce bana tarayıcıda Dog CEO çağrısını yaptır ve
cevabın her alanını sorgula. Sonra public-apis'ten ilgi alanıma göre bir API seçtir,
mini-widget planı kurdur ve maliyet+limit denetimini bana yaptır. Sonunda 5 kontrol
sorusunu sor.

🔄 Güncelleme istemi (bu rehber bayatlarsa)

api-rehberi.md'yi güncelle: örnek API'lerin (dog.ceo, open-meteo, frankfurter) hâlâ
canlı ve anahtarsız olduğunu TEST ederek doğrula; LLM fiyat örneklerini resmî
listelerden tazele; public-apis reposunun durumunu kontrol et; "Son tarama"yı yenile.

---

Bu rehber nerede derinleşiyor? (sarmal harita)

• API kavramı + MCP → kavramlar-seviye-3 ve 3.4 · secret disiplini/rotasyon → [2.6]
• LLM API fiyat manzarası ve model seçimi → llm-haritasi.md · görsel/video/ses API'leri → uretim-rehberi.md
• maliyet düşünme becerisi → [4.4]

Kaynaklar (9 Tem 2026): public-apis · Open-Meteo · Frankfurter · Dog CEO — üçü de bu tarama gününde canlı test edildi · LLM fiyatları: Claude / Gemini / DeepSeek resmî sayfaları.