Dış API'lere bağlanmak

Ders 15'te Node'dan, Ders 24'te tarayıcıdan Data Dragon'a istek attın. Data Dragon kim olduğunu sormaz, sınır koymaz, çoğu zaman hızlı cevap verir. Gerçek servislerin çoğu öyle değildir: anahtar ister, ne sıklıkla istek atabileceğini sınırlar, bazen geç cevap verir, bazen hiç vermez. Bu derste kendi sunucunu dış servislerle konuşturuyorsun. Anahtarı gizli tutmayı, API belgesi okumayı, cevap gelmezse vazgeçmeyi, geçici hatalarda yeniden denemeyi, 429'a uymayı ve aynı soruyu tekrar tekrar sormamayı öğreneceksin. Dersin sonunda tarayıcının yalnız senin API'nle konuştuğu, anahtarın sunucuda kaldığı bir ara sunucun olacak.

#Anahtar tarayıcıya girmez

Ders 25'teki ansiklopedine bir özellik eklemek istediğini düşün: ziyaretçi Riot ID'sini yazsın, sayfa onun hesabını göstersin. Bu bilgi Data Dragon'da yok, Riot'un asıl API'sinde. O API her istekte bir API anahtarı ister: Riot'un sana verdiği, seni tanıtan gizli bir metin. Ders 24'te "anahtarlı API'leri kendi sunucundan çağırmayı Blok 4'te öğreneceksin" demiştik; nedenini şimdi göreceksin. İlk akla gelen, js klasöründe hesap.js adında bir dosya açıp anahtarı oraya yazmak ve fetch'in başlığına koymak:

1const anahtar = "RGAPI-12345678-abcd-4ef0-9876-0123456789ab"2 3const yanit = await fetch("https://europe.api.riotgames.com/riot/account/v1/accounts/by-riot-id/Sihirdar/TR1", {4    headers: { "X-Riot-Token": anahtar }5})

Bu kod çalışır bile: denediğimizde Riot'un sunucusu tarayıcıdan gelen bu isteğe CORS izni verdi. Sorun başka yerde. js/hesap.js sayfanı açan herkesin tarayıcısına iner ve tarayıcıya giden hiçbir şey gizli kalmaz. Ziyaretçi F12'ye basıp Network sekmesinde isteğe tıklasa X-Riot-Token başlığını olduğu gibi görür (Ders 24). Tarayıcıya bile gerek yok; sayfa Live Server'da açıkken dosyayı terminalden indirmek yeter:

PS C:\kod\ansiklopedi> curl.exe http://localhost:5500/js/hesap.jsconst anahtar = "RGAPI-12345678-abcd-4ef0-9876-0123456789ab" const yanit = await fetch("https://europe.api.riotgames.com/riot/account/v1/accounts/by-riot-id/Sihirdar/TR1", {    headers: { "X-Riot-Token": anahtar }})

Sayfayı GitHub Pages'e koyduysan (Ders 25) aynı dosya https://kullanici-adin.github.io/ansiklopedi/js/hesap.js adresinde bütün internete açık durur. .env ve .gitignore burada seni kurtarmaz: anahtar Git'e girmese bile tarayıcıya giden dosyanın içindedir.

Anahtarı ele geçiren biri senin adına istek atar: hız sınırını o doldurur, kurallara aykırı kullanılan anahtar kapatılır ve senin projen durur. Riot'un kuralları da açık: anahtarını güvende tutmak bir ürünü yayına açmanın şartı, güvende tutulmayan anahtar iptal edilebilir.

Çözüm, isteği tarayıcının değil senin sunucunun atması. Tarayıcı senin API'ne sorar; senin sunucun anahtarı .env'den alıp Riot'a sorar ve cevabı geri iletir. Araya giren bu sunucuya ara sunucu (proxy) denir.

Ara sunucunun faydası yalnız gizlilik değil:

• Sınırları sen yönetirsin. Anahtarın hız sınırı bütün ziyaretçilerin için ortaktır. Aynı soruyu tekrar tekrar sormak yerine cevabı bir süre saklarsın; bu derste göreceksin.
• Cevabı sen biçimlersin. Dış servisin kocaman JSON'undan sayfanın ihtiyacı olan birkaç alanı seçip gönderirsin.
• CORS derdi biter. Ders 24'teki CORS bir tarayıcı kuralıydı; sunucudan sunucuya istekte yoktur.
• Değişiklik tek yerde kalır. Dış servisin adresi ya da anahtarın değişirse yalnız sunucunu güncellersin, sayfa aynı kalır.

#API belgesi okumak

Her API'nin kendi adresleri, parametre adları ve kuralları vardır; bunları tahminle bulamazsın. Hepsini API belgesi (documentation) söyler.

Belgeyi baştan sona okumana gerek yok. Beş sorunun cevabını arıyorsun:

İlk denemeyi Open-Meteo ile yapacağız: ücretsiz, anahtarsız bir hava durumu API'si. LoL'le ilgisi yok, ama anahtar istemediği için her çıktıyı kendi bilgisayarında hemen görebilirsin; Riot'un anahtarlı API'sine birazdan geçeceğiz. Belgeyi open-meteo.com/en/docs adresinde aç ve beş sorunun cevabını bul. Bu ders yazılırken bulduklarımız:

Sınırlar ve ücretsiz kullanımın koşulları belgenin Terms sayfasında. Reklam ya da abonelikle para kazanan bir sitede ücretsiz sürümü kullanamazsın. Belgelerin sayfaları da sayıları da zamanla değişebilir; bir API'yi kullanmadan önce hep güncel belgeye bak.

Belgedeki örnek adresi tarayıcıya yapıştırabilir ya da terminalden isteyebilirsin. & işareti PowerShell'de özel bir anlam taşıdığı için adresi tırnak içine al:

PS C:\kod> curl.exe "https://api.open-meteo.com/v1/forecast?latitude=41.01&longitude=28.98&current=temperature_2m,wind_speed_10m&timezone=auto"{"latitude":41.02444,"longitude":28.940546,"generationtime_ms":0.043392181396484375,"utc_offset_seconds":10800,"timezone":"Europe/Istanbul","timezone_abbreviation":"GMT+3","elevation":36.0,"current_units":{"time":"iso8601","interval":"seconds","temperature_2m":"°C","wind_speed_10m":"km/h"},"current":{"time":"2026-10-11T20:45","interval":900,"temperature_2m":21.1,"wind_speed_10m":1.6}}

Cevap tek uzun satır; terminali sağa kaydırarak okuyabilirsin. Aynı cevabı okunsun diye satırlara böldük:

{  "latitude": 41.02444,  "longitude": 28.940546,  "generationtime_ms": 0.043392181396484375,  "utc_offset_seconds": 10800,  "timezone": "Europe/Istanbul",  "timezone_abbreviation": "GMT+3",  "elevation": 36.0,  "current_units": {    "time": "iso8601",    "interval": "seconds",    "temperature_2m": "°C",    "wind_speed_10m": "km/h"  },  "current": {    "time": "2026-10-11T20:45",    "interval": 900,    "temperature_2m": 21.1,    "wind_speed_10m": 1.6  }}

Cevabı belgeyle yan yana oku. current içinde istediğin iki değer var, birimleri current_units'te: °C ve km/h. interval: 900 bu değerlerin 900 saniyelik, yani 15 dakikalık dilimlerle hesaplandığını söylüyor; önbellek kurarken işine yarayacak. Koordinatların biraz değiştiğine de dikkat et: Open-Meteo hava modelinin en yakın ızgara noktasını kullanır. Sayılar sende farklı çıkacak; hava değişiyor.

Bir parametre adını yanlış yazarsan ne olur? temperature_2m yerine Türkçesini dene:

PS C:\kod> curl.exe -i "https://api.open-meteo.com/v1/forecast?latitude=41.01&longitude=28.98&current=sicaklik"HTTP/1.1 400 Bad RequestDate: Sun, 11 Oct 2026 17:58:00 GMTContent-Type: application/json; charset=utf-8Content-Length: 218Connection: keep-alive {"error":true,"reason":"Invalid value: Cannot initialize SurfacePressureAndHeightVariable<VariableAndPreviousDay, VariableOrSpread<ForecastPressureVariable>, ForecastHeightVariable> from invalid String value sicaklik"}

400 Bad Request ve gövdede sebep (reason); error ile reason alanlarının sırası sende ters çıkabilir, JSON'da alan sırası önemsizdir. Mesaj uzun ve karışık, ama son sözcükleri yetiyor: invalid String value sicaklik, yani sicaklik geçersiz bir değer. Parametre adlarını belgeden harfi harfine kopyala; API'ler tahmini ya da Türkçe ad tanımaz.

#Sunucuda fetch

Bu dersin projesi için yeni bir klasör aç: terminalde cd C:\kod, mkdir sihirdar-api ve cd sihirdar-api. Klasörü VS Code'da aç, Ders 27'deki gibi npm init -y ile package.json oluştur ve Ders 28'deki Express'i kur:

PS C:\kod\sihirdar-api> npm install expressadded 65 packages, and audited 66 packages in 1s 28 packages are looking for funding  run `npm fund` for details found 0 vulnerabilities

Bu ders Express 5.3.0 ile denendi; seninki daha yeni olabilir. package.json'da "type" satırını "commonjs"'ten "module"'e çevir ve scripts kısmındaki test satırının yerine iki betik yaz. dev, Ders 29'daki gibi .env dosyasını okuyarak ve Ders 27'deki gibi her kayıtta yeniden başlayarak çalışır:

1{2  "name": "sihirdar-api",3  "version": "1.0.0",4  "description": "",5  "main": "index.js",6  "scripts": {7    "dev": "node --watch --env-file=.env app.js",8    "start": "node --env-file=.env app.js"9  },10  "keywords": [],11  "author": "",12  "license": "ISC",13  "type": "module",14  "dependencies": {15    "express": "^5.3.0"16  }17}

Birazdan anahtar yazacağın .env dosyası Git'e asla girmemeli; işe .gitignore ile başla:

1node_modules2.env

İlk dış isteği bir sunucu kurmadan, düz bir dosyadan at. Proje klasöründe hava.js adında bir dosya aç ve belgede kurduğun adresi koda dök. Soldaki dosya listesinde artık node_modules, .gitignore, hava.js, package-lock.json ve package.json duruyor; aşağıdaki pencerede kod sığsın diye listeyi gizledik.

1const parametreler = new URLSearchParams({2    latitude: "41.01",3    longitude: "28.98",4    current: "temperature_2m,wind_speed_10m",5    timezone: "auto"6})7const adres = "https://api.open-meteo.com/v1/forecast?" + parametreler8console.log(adres)9 10const yanit = await fetch(adres)11const veri = await yanit.json()12console.log(veri.current)13const sicaklik = veri.current.temperature_2m14const ruzgar = veri.current.wind_speed_10m15console.log(`İstanbul: ${sicaklik} °C, rüzgâr ${ruzgar} km/sa`)

PS C:\kod\sihirdar-api> node hava.jshttps://api.open-meteo.com/v1/forecast?latitude=41.01&longitude=28.98&current=temperature_2m%2Cwind_speed_10m&timezone=auto{  time: '2026-10-11T21:00',  interval: 900,  temperature_2m: 21,  wind_speed_10m: 1.6}İstanbul: 21 °C, rüzgâr 1.6 km/sa

• Ders 25'te adresteki sorguyu okumak için kullandığın URLSearchParams tersini de yapar: bir objeden sorgu metni kurar ve özel işaretleri kodlar. Çıktının ilk satırını sağa kaydırırsan current=temperature_2m%2Cwind_speed_10m kısmını görürsün: virgül %2C oldu. Metne eklenince kendiliğinden latitude=41.01&... metnine dönüşür. Adresi elle birleştirmek de çalışırdı, ama bir değerin içinde boşluk, & ya da Türkçe harf olunca adres bozulur; kodlama işini ona bırak.
• fetch Node'da tarayıcıdakiyle aynıdır (Ders 15). Fark nerede çalıştığında: bu kodu ziyaretçi hiç görmez, CORS da ona karışmaz.
• yanit.ok denetimini şimdilik atladık. Birazdan bütün denetimleri tek bir fonksiyonda toplayacağız.

#Riot Games API'si: anahtar, sınırlar, bölgeler

Riot'un asıl API'si oyuncu hesaplarını, maç geçmişlerini ve lig sıralamalarını verir. Belgesi developer.riotgames.com adresinde. Data Dragon'dan iki farkı var: her istek bir anahtar ister ve her anahtarın bir hız sınırı vardır. Anahtarı şöyle alırsın:

Portalın görünümü değişmiş olabilir; adımlar aynı kalır: giriş yap, anahtarı kopyala, süresi dolunca yenile. Riot'ta üç tür anahtar var:

Sayılar bu ders yazılırken Riot'un belgesinde yazanlar. Belge geliştirici anahtarı için ayrı bir sayı vermiyor; kendi anahtarının sınırına portalda bak. Sınırlar nasıl sayılır?

• Bölge başına. Türkiye sunucusuna attığın istekler ile Batı Avrupa sunucusuna attıkların ayrı sayılır.
• Uygulama sınırı ve metot sınırı. Uygulama sınırı, anahtarınla bir bölgede attığın bütün isteklerin toplamıdır. Metot sınırı ise her uç nokta için ayrıca sayılır.
• Aşarsan 429. Yanıtın Retry-After başlığı kaç saniye bekleyeceğini söyler. Belgeye göre o süre boyunca hiç istek atmamalısın; kurala uymayan uygulamaların erişimi kapatılabilir.

#Platform ve bölge adresleri

Riot'un tek bir adresi yok. Bazı veriler bir oyun sunucusuna aittir, bazıları bir bölgedeki bütün sunuculara ortaktır:

TR sunucusundaki bir oyuncu için platform tr1, bölge europe. Hesap uç noktasının (account-v1) belgesi yalnız üç bölge sayıyor: americas, asia ve europe. Belgeye göre herhangi bir hesabı herhangi bir bölgeden sorabilirsin, ama en yakın kümeyi kullanman öneriliyor; Türkiye'den en yakını europe. Bir uç noktanın platform mu bölge mi istediğini o uç noktanın belge sayfası söyler.

Oyundaki adın Sihirdar#TR1 gibi iki parçalıdır: oyun adı (gameName) ve etiket (tagLine). Hesap uç noktası bu ikisinden PUUID'yi bulur: hesabın hiç değişmeyen, 78 karakterlik kimliği. Maç geçmişi gibi öteki uç noktalar oyuncuyu bu kimlikle ister. Adreste # yok, çünkü # adreste parça (fragment) demektir ve sunucuya hiç gitmez (Ders 18). Bu yüzden API, oyun adını ve etiketi iki ayrı yol parçası olarak alır:

Belgede yanıt kodlarının listesi de var. Hangisinde ne yapacağın daha sonra yeniden deneme kurarken işine yarayacak:

Belge ile gerçek her zaman birebir tutmaz. Bu ders yazılırken uydurma bir anahtarla denediğimizde Riot 403 değil, 401 döndürdü. Kodun ikisini de "anahtar sorunu" saymalı. Riot'un belgesi bir şey daha söylüyor: başarısız yanıtların gövdesi olmayabilir, olsa da JSON olmayabilir; kararını gövdeye değil durum koduna göre ver.

#Anahtarı başlıkta göndermek

Anahtarını aldıysan proje klasöründe .env adında bir dosya aç ve tek satır yaz. Almadıysan aşağıdaki uydurma anahtarla devam et; bu bölümdeki hataların hepsini yine kendin görürsün.

1RIOT_API_KEY=RGAPI-12345678-abcd-4ef0-9876-0123456789ab

Sonra riot.js dosyasını yaz. Kendi Riot ID'n varsa ad ile etiket'e onu yaz:

1const ad = "Sihirdar"2const etiket = "TR1"3const adres = "https://europe.api.riotgames.com/riot/account/v1/accounts/by-riot-id/"4    + encodeURIComponent(ad) + "/" + encodeURIComponent(etiket)5 6const yanit = await fetch(adres, {7    headers: { "X-Riot-Token": process.env.RIOT_API_KEY }8})9console.log(yanit.status)10console.log(await yanit.json())

• encodeURIComponent (Ders 25) oyun adındaki boşluğu ve Türkçe harfleri adrese uygun hâle getirir: Kırmızı Ejder → K%C4%B1rm%C4%B1z%C4%B1%20Ejder.
• headers objesi isteğe başlık ekler. Ders 26'da GitHub'a anahtarı Authorization: Bearer … başlığında göndermiştin; Riot başka bir başlık istiyor, X-Riot-Token. Anahtarın hangi başlıkta gideceğini her zaman belge söyler.
• Anahtar kodda değil, process.env'den geliyor.
• 4. satır + ile başlıyor: JavaScript önceki satırı bitmemiş sayar ve ikisini tek ifade olarak okur. Uzun bir adresi böyle bölebilirsin.

PS C:\kod\sihirdar-api> node --env-file=.env riot.js401{ status: { message: 'Unknown apikey', status_code: 401 } }

Uydurma anahtarla 401 ve Unknown apikey (tanınmayan anahtar) geldi. Geçerli bir anahtarla gelecek cevap aşağıdakine benzer. Bu çıktı bir örnek: bu ders geçerli bir anahtar olmadan yazıldı. Alan adları Riot'un belgesindeki gibi; puuid gerçekte harf ve rakamlardan oluşan 78 karakterlik bir metin.

200{  puuid: 'aB3x…78 karakterlik kimlik…Qz9',  gameName: 'Sihirdar',  tagLine: 'TR1'}

PS C:\kod\sihirdar-api> node riot.js401{ status: { message: 'Forbidden', status_code: 401 } }

6const yanit = await fetch(adres, {7    header: { "X-Riot-Token": process.env.RIOT_API_KEY }8})

PS C:\kod\sihirdar-api> node --env-file=.env riot.js401{  status: {    message: 'Cannot process request apikey or authorization header is empty',    status_code: 401  }}

#Her yanıtı denetleyen tek fonksiyon

riot.js, hava.js ve sunucundaki her uç nokta aynı denetimleri yapmalı: durum kodu başarılı mı, gelen şey gerçekten JSON mu? Ders 15'te ve Ders 24'te bunun için küçük bir jsonGetir yazmıştın: getir, yanit.ok'u denetle, JSON'a çevir. Şimdi daha güçlüsünü yazıp bir modüle koyacaksın (Ders 14); sunucundaki her dış istek onu kullanacak. disIstek.js adında bir dosya aç:

1export class DisServisHatasi extends Error {2    constructor(durum, mesaj) {3        super(mesaj)4        this.name = "DisServisHatasi"5        this.durum = durum6    }7}8 9export async function jsonGetir(adres, basliklar = {}) {10    const yanit = await fetch(adres, { headers: basliklar })11    if (!yanit.ok) {12        const govde = await yanit.text()13        const ilkSatir = govde.split("\n")[0].slice(0, 120)14        throw new DisServisHatasi(yanit.status, `${yanit.status} ${ilkSatir}`)15    }16    const tur = yanit.headers.get("content-type") ?? ""17    if (!tur.includes("application/json")) {18        throw new DisServisHatasi(yanit.status, `JSON yerine ${tur} geldi`)19    }20    return await yanit.json()21}

• DisServisHatasi, Ders 16'daki gibi kendi hata sınıfımız. Error'dan türediği için mesajı ve yığın izi var; üstüne durum alanında durum kodunu taşıyor. Hangi hatanın yeniden denenmeye değer olduğuna birazdan bu alana bakarak karar vereceğiz.
• Yanıt başarısızsa gövdeyi text() ile düz metin olarak oku (Ders 26): gövde JSON olmayabilir, hiç olmayabilir de. Mesaja yalnız ilk satırı, en çok 120 harf koyuyoruz; bütün bir HTML sayfası terminali doldurmasın.
• Yanıt başarılı olsa bile gelen şeyin JSON olduğunu Content-Type'tan denetle. Neden gerektiğini hemen aşağıdaki hata kartında göreceksin.

riot.js'i bu fonksiyonla yeniden yaz:

1import { jsonGetir } from "./disIstek.js"2 3const ad = "Sihirdar"4const etiket = "TR1"5const adres = "https://europe.api.riotgames.com/riot/account/v1/accounts/by-riot-id/"6    + encodeURIComponent(ad) + "/" + encodeURIComponent(etiket)7 8try {9    const hesap = await jsonGetir(adres, { "X-Riot-Token": process.env.RIOT_API_KEY })10    console.log(hesap)11} catch (hata) {12    console.log(hata.name, hata.durum)13    console.log(hata.message)14}

PS C:\kod\sihirdar-api> node --env-file=.env riot.jsDisServisHatasi 401401 {"status":{"message":"Unknown apikey","status_code":401}}

Program artık çökmüyor; ne olduğunu, hangi kodla olduğunu iki satırda söylüyor.

1const yanit = await fetch("https://open-meteo.com/en/docs")2console.log(yanit.status, yanit.ok)3const veri = await yanit.json()4console.log(veri.current)

200 true<anonymous_script>:1<!doctype html>^ SyntaxError: Unexpected token '<', "<!doctype "... is not valid JSON    at JSON.parse (<anonymous>)    at parseJSONFromBytes (node:internal/deps/undici/undici:4394:19)    ... Node.js v24.20.0

1import { jsonGetir } from "./disIstek.js"2 3try {4    const veri = await jsonGetir("https://open-meteo.com/en/docs")5    console.log(veri)6} catch (hata) {7    console.log(hata.message)8}

PS C:\kod\sihirdar-api> node deneme.jsJSON yerine text/html; charset=utf-8 geldi

#Zaman aşımı: sonsuza dek bekleme

Dış servis her zaman hızlı cevap vermez. Bazen yük altındadır, bazen ağın bir yerinde tıkanıklık vardır, bazen istek hiç cevaplanmaz; Ders 27'de res.end'i unuttuğunda olduğu gibi. fetch böyle bir servisi dakikalarca bekler. Senin sunucunda bunun anlamı şu: ziyaretçinin isteği de bekler, cevapsız istekler birikir, sayfa "yükleniyor"da takılı kalır.

Gerçek bir servisin ne zaman yavaşlayacağını sen seçemezsin. Bu yüzden onun huysuz hâllerini taklit eden küçük bir sahte servis yazacağız. Gerçek projelerde de böyle yapılır: kötü günü beklemek yerine kötü günü kendin üretirsin. Bu derste sahte servise üç yol ekleyeceksin: geç cevap veren, ara sıra hata veren ve sık sorunca 429 döndüren. İlki için proje klasöründe sahte-servis.js dosyasını aç:

1import express from "express"2 3const app = express()4const port = 40005 6function bekle(ms) {7    return new Promise((resolve) => setTimeout(resolve, ms))8}9 10app.use((req, res, next) => {11    console.log(new Date().toLocaleTimeString("tr-TR"), req.method, req.url)12    next()13})14 15app.get("/yavas", async (req, res) => {16    await bekle(3000)17    res.json({ mesaj: "Geç de olsa geldim" })18})19 20app.listen(port, (hata) => {21    if (hata) {22        throw hata23    }24    console.log(`Sahte servis çalışıyor: http://localhost:${port}`)25})

• bekle, Ders 15'teki fonksiyon. /yavas her isteği 3 saniye bekletip öyle cevaplar.
• Ara katman (Ders 28) gelen her isteği saatiyle yazar: 21:12:41 GET /yavas gibi. toLocaleTimeString, Ders 17'deki toLocaleString'in yalnız saati yazan kardeşi. Servise ne zaman, kaç istek geldiğini buradan izleyeceğiz.
• Port 4000: ara sunucun 3000'de çalışacak, ikisi çakışmasın. Bu derste iki sunucu birden çalıştıracağın için listen'daki hata denetimi (Ders 28) önemli: kapı doluysa sunucu sessizce "çalışıyor" demez, hatayla durur.

İkinci bir terminal aç (Ders 27) ve servisi --watch ile başlat; yeni yollar ekledikçe kendini yenilesin:

PS C:\kod\sihirdar-api> node --watch sahte-servis.jsSahte servis çalışıyor: http://localhost:4000

İlk terminalde yavas.js dosyasını yaz ve çalıştır. Süreyi Ders 15'teki console.time ile ölçüyoruz:

1console.time("süre")2const yanit = await fetch("http://localhost:4000/yavas")3console.log(await yanit.json())4console.timeEnd("süre")

PS C:\kod\sihirdar-api> node yavas.js{ mesaj: 'Geç de olsa geldim' }süre: 3.114s

Şimdi isteğe bir süre sınırı koy. fetch'in ayar objesindeki signal (sinyal) alanı, isteği yarıda kesebilen bir kumanda alır. AbortSignal.timeout(2000) 2000 milisaniye sonra kendiliğinden basılan bir kumanda üretir:

1console.time("süre")2const yanit = await fetch("http://localhost:4000/yavas", {3    signal: AbortSignal.timeout(2000)4})5console.log(await yanit.json())6console.timeEnd("süre")

PS C:\kod\sihirdar-api> node yavas.jsnode:internal/modules/run_main:107    triggerUncaughtException(    ^ [DOMException [TimeoutError]: The operation was aborted due to timeout] Node.js v24.20.0

1console.time("süre")2try {3    const yanit = await fetch("http://localhost:4000/yavas", {4        signal: AbortSignal.timeout(2000)5    })6    console.log(await yanit.json())7} catch (hata) {8    console.log(hata.name + ": " + hata.message)9}10console.timeEnd("süre")

PS C:\kod\sihirdar-api> node yavas.jsTimeoutError: The operation was aborted due to timeoutsüre: 2.005s

Program tam 2 saniyede vazgeçti. Sahte servisin terminaline bak:

21:12:41 GET /yavas21:12:44 GET /yavas21:12:46 GET /yavas

Üç çalıştırma, üç istek. Servis, senin vazgeçtiğinden habersiz her isteği yine 3 saniyede bitirdi. Zaman aşımı yalnız senin beklemeni keser; karşı tarafın işini durdurmaz.

Kaç saniye vermelisin? Servisin normalde ne kadar sürdüğüne bak ve birkaç katını ver. Open-Meteo'ya attığımız istekler yarım saniyenin altında döndü; 2 saniye cömert bir sınır. Unutma: tarayıcıdaki ziyaretçi senin sunucunu, senin sunucun da dış servisi bekliyor. Ziyaretçiyi ne kadar bekletebileceğini düşün; dış servise tanıdığın süre ondan kısa olmalı.

Süre sınırını jsonGetir'e ekle; böylece her dış istek kendiliğinden korunur. fetch satırını şöyle değiştir:

9export async function jsonGetir(adres, basliklar = {}) {10    const yanit = await fetch(adres, {11        headers: basliklar,12        signal: AbortSignal.timeout(2000)13    })

#Yeniden denemek ve artan bekleme

Bir istek başarısız oldu. Yeniden denemeli misin? Cevap, hatanın türüne bağlı. Ders 26'daki kural burada da geçerli: 4 ile başlayan kodlar "sorun sende" der, aynı isteği yeniden göndermek bir şey değiştirmez. 5 ile başlayanlar, zaman aşımı ve bağlantı kopması ise çoğu zaman geçicidir; az sonra aynı istek başarılı olabilir. Tek istisna 429: isteğin doğru, ama çok sık soruyorsun; beklersen geçer.

Hemen yeniden denemek de iyi fikir değil. Servis yük altında olduğu için hata veriyorsa, ona üst üste yeni istekler göndermek onu daha da boğar.

Sahte servise ara sıra hata veren bir yol ekle. /yavas'ın altına yaz:

20let istekSayisi = 021 22app.get("/kararsiz", (req, res) => {23    istekSayisi = istekSayisi + 124    if (istekSayisi % 3 !== 0) {25        res.status(503).json({ hata: "Servis meşgul" })26        return27    }28    res.json({ mesaj: "Bu sefer oldu", istek: istekSayisi })29})

Her üç istekten ilk ikisi 503 Service Unavailable (servis kullanılamıyor) alır, üçüncüsü başarılı olur; % kalanı Ders 1'den tanıyorsun. Şimdi yeniden deneyen fonksiyonu disIstek.js'in sonuna ekle:

26function bekle(ms) {27    return new Promise((resolve) => setTimeout(resolve, ms))28}29 30function geciciMi(hata) {31    if (hata.name === "TimeoutError" || hata.message === "fetch failed") {32        return true33    }34    return hata.durum === 429 || hata.durum >= 50035}36 37export async function yenidenDene(is, denemeSayisi = 3) {38    let bekleme = 50039    for (let deneme = 1; deneme <= denemeSayisi; deneme++) {40        try {41            return await is()42        } catch (hata) {43            if (deneme === denemeSayisi || !geciciMi(hata)) {44                throw hata45            }46            console.log(`${deneme}. deneme olmadı (${hata.message}). ${bekleme} ms sonra yeniden.`)47            await bekle(bekleme)48            bekleme = bekleme * 249        }50    }51}

• is, yeniden denenecek işi yapan bir fonksiyon. yenidenDene onu her denemede baştan çağırır; ona sonucu değil, sonucu üreten fonksiyonu veriyorsun (Ders 10).
• return await is(): iş başarılı olursa sonucu döndür, döngü biter. Hata olursa catch'e düşülür.
• Son denemeyse ya da hata geçici değilse hatayı olduğu gibi yukarı fırlat. Yakalayıp yutmuyoruz (Ders 13).
• Yoksa bekle ve bir sonraki bekleme için süreyi ikiye katla.
• geciciMi, yukarıdaki tablonun koda dökülmüş hâli. fetch failed, isteğin sunucuya hiç ulaşamadığı durumdur (Ders 15).

deneme.js'in içini şununla değiştir ve çalıştır:

1import { jsonGetir, yenidenDene } from "./disIstek.js"2 3console.time("toplam")4const veri = await yenidenDene(() => jsonGetir("http://localhost:4000/kararsiz"))5console.log(veri)6console.timeEnd("toplam")

PS C:\kod\sihirdar-api> node deneme.js1. deneme olmadı (503 {"hata":"Servis meşgul"}). 500 ms sonra yeniden.2. deneme olmadı (503 {"hata":"Servis meşgul"}). 1000 ms sonra yeniden.{ mesaj: 'Bu sefer oldu', istek: 3 }toplam: 1.641s

21:13:02 GET /kararsiz21:13:02 GET /kararsiz21:13:03 GET /kararsiz

Servis üç istek gördü: ikisini reddetti, üçüncüsünü cevapladı. Toplam süre, 500 ve 1000 milisaniyelik iki bekleme artı isteklerin kendi süreleri. İkinci kez çalıştırırsan istek: 6 görürsün; sayaç servis yeniden başlayana kadar kaldığı yerden sayar.

Şimdi yeniden denemeye değmeyen bir hata dene: deneme.js'teki adresi /kararsiz yerine olmayan bir yol yap, /yok:

PS C:\kod\sihirdar-api> node deneme.jsfile:///C:/kod/sihirdar-api/disIstek.js:17        throw new DisServisHatasi(yanit.status, `${yanit.status} ${ilkSatir}`)              ^ DisServisHatasi: 404 <!DOCTYPE html>    at jsonGetir (file:///C:/kod/sihirdar-api/disIstek.js:17:15)    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async yenidenDene (file:///C:/kod/sihirdar-api/disIstek.js:41:20)    at async file:///C:/kod/sihirdar-api/deneme.js:4:14 {  durum: 404} Node.js v24.20.0

Hiç "deneme olmadı" satırı yok: 404 geçici değil, yenidenDene ilk hatada vazgeçti. Express, olmayan bir yola kendi HTML sayfasıyla cevap verdiği için mesajda <!DOCTYPE html> var. Yığın izini aşağıdan yukarı oku (Ders 13): deneme.js:4 yenidenDene'yi çağırdı, o jsonGetir'i çağırdı, hata disIstek.js:17'deki throw'da fırladı. Hatanın sonundaki durum: 404, sınıfımıza eklediğimiz alan. Denedikten sonra adresi yeniden /kararsiz yap.

40        try {41            return is()42        } catch (hata) {

PS C:\kod\sihirdar-api> node deneme.jsfile:///C:/kod/sihirdar-api/disIstek.js:17        throw new DisServisHatasi(yanit.status, `${yanit.status} ${ilkSatir}`)              ^ DisServisHatasi: 503 {"hata":"Servis meşgul"}    at jsonGetir (file:///C:/kod/sihirdar-api/disIstek.js:17:15)    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async file:///C:/kod/sihirdar-api/deneme.js:4:14 {  durum: 503} Node.js v24.20.0

PS C:\kod\sihirdar-api> node deneme.js1. deneme olmadı (fetch failed). 500 ms sonra yeniden.2. deneme olmadı (fetch failed). 1000 ms sonra yeniden.node:internal/modules/run_main:107    triggerUncaughtException(    ^ [TypeError: fetch failed] {  [cause]: AggregateError [ECONNREFUSED]:       ...    code: 'ECONNREFUSED',    [errors]: [      Error: connect ECONNREFUSED ::1:4000          ...        errno: -4078,        code: 'ECONNREFUSED',        syscall: 'connect',        address: '::1',        port: 4000      },      Error: connect ECONNREFUSED 127.0.0.1:4000          ...        errno: -4078,        code: 'ECONNREFUSED',        syscall: 'connect',        address: '127.0.0.1',        port: 4000      }    ]  }} Node.js v24.20.0

#Hız sınırı: 429 ve Retry-After

Riot'un kişisel anahtarı bir saniyede 20, iki dakikada 100 istek atabilir. Bu senin değil, anahtarın sınırı: siteni aynı anda yüz kişi kullanıyorsa yüzünün isteği de aynı sınırdan düşer. Sınırı aşan istek 429 Too Many Requests (çok fazla istek) alır; Retry-After başlığı kaç saniye sonra yeniden deneyebileceğini söyler.

Sahte servise üç saniyede yalnız bir isteğe izin veren bir yol ekle:

31let sonIzin = 032 33app.get("/sinirli", (req, res) => {34    const gecen = Date.now() - sonIzin35    if (gecen < 3000) {36        const kalan = Math.ceil((3000 - gecen) / 1000)37        res.set("Retry-After", String(kalan))38        res.status(429).json({ hata: "Çok sık istek attın" })39        return40    }41    sonIzin = Date.now()42    res.json({ mesaj: "Buyur, taze veri" })43})

• Date.now() (Ders 23) şu anı milisaniye olarak verir. Son izinden bu yana 3000 ms geçmediyse 429.
• res.set("Retry-After", ...) yanıta bir başlık ekler. Değer saniye cinsinden bir metin; Math.ceil yukarı yuvarlar, 2,4 saniye kaldıysa 3 yazar.
• Kendi API'ne böyle bir sınır koymayı Ders 31'de göreceksin; buradaki sayaç yalnız deney için.

İlk terminalden arka arkaya iki istek at:

PS C:\kod\sihirdar-api> curl.exe -i http://localhost:4000/sinirliHTTP/1.1 200 OKX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 28ETag: W/"1c-gl2dmevYKYHYri1iik8KeH1f/Uk"Date: Sun, 11 Oct 2026 18:13:29 GMTConnection: keep-aliveKeep-Alive: timeout=5 {"mesaj":"Buyur, taze veri"}PS C:\kod\sihirdar-api> curl.exe -i http://localhost:4000/sinirliHTTP/1.1 429 Too Many RequestsX-Powered-By: ExpressRetry-After: 3Content-Type: application/json; charset=utf-8Content-Length: 33ETag: W/"21-eFit0VoCMedPBP/11ZdCOpSy2bI"Date: Sun, 11 Oct 2026 18:13:29 GMTConnection: keep-aliveKeep-Alive: timeout=5 {"hata":"Çok sık istek attın"}

İkinci istek aynı saniyede gitti: 429 ve Retry-After: 3. X-Powered-By ve ETag başlıklarını Express kendiliğinden ekler. Şimdi aynı yolu programdan, yenidenDene ile üç kez arka arkaya iste. curl.exe denemesinden sonra üç saniye geçmesini bekle ve deneme.js'in içini şununla değiştir:

1import { jsonGetir, yenidenDene } from "./disIstek.js"2 3for (let i = 1; i <= 3; i++) {4    console.time(`${i}. istek`)5    const veri = await yenidenDene(() => jsonGetir("http://localhost:4000/sinirli"))6    console.log(veri.mesaj)7    console.timeEnd(`${i}. istek`)8}

PS C:\kod\sihirdar-api> node deneme.jsBuyur, taze veri1. istek: 68.77ms1. deneme olmadı (429 {"hata":"Çok sık istek attın"}). 500 ms sonra yeniden.2. deneme olmadı (429 {"hata":"Çok sık istek attın"}). 1000 ms sonra yeniden.file:///C:/kod/sihirdar-api/disIstek.js:17        throw new DisServisHatasi(yanit.status, `${yanit.status} ${ilkSatir}`)              ^ DisServisHatasi: 429 {"hata":"Çok sık istek attın"}    at jsonGetir (file:///C:/kod/sihirdar-api/disIstek.js:17:15)    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)    at async yenidenDene (file:///C:/kod/sihirdar-api/disIstek.js:41:20)    at async file:///C:/kod/sihirdar-api/deneme.js:5:18 {  durum: 429} Node.js v24.20.0

disIstek.js'te iki yeri değiştir. Önce hata sınıfı ve jsonGetir başlığı okusun:

1export class DisServisHatasi extends Error {2    constructor(durum, mesaj, tekrarSaniye) {3        super(mesaj)4        this.name = "DisServisHatasi"5        this.durum = durum6        this.tekrarSaniye = tekrarSaniye7    }8}9 10export async function jsonGetir(adres, basliklar = {}) {11    const yanit = await fetch(adres, {12        headers: basliklar,13        signal: AbortSignal.timeout(2000)14    })15    if (!yanit.ok) {16        const govde = await yanit.text()17        const ilkSatir = govde.split("\n")[0].slice(0, 120)18        const tekrar = Number(yanit.headers.get("retry-after"))19        throw new DisServisHatasi(yanit.status, `${yanit.status} ${ilkSatir}`, tekrar)20    }

Sonra yenidenDene o süreye uysun:

39export async function yenidenDene(is, denemeSayisi = 3) {40    let bekleme = 50041    for (let deneme = 1; deneme <= denemeSayisi; deneme++) {42        try {43            return await is()44        } catch (hata) {45            const sure = hata.tekrarSaniye ? hata.tekrarSaniye * 1000 : bekleme46            if (deneme === denemeSayisi || !geciciMi(hata) || sure > 10000) {47                throw hata48            }49            console.log(`${deneme}. deneme olmadı (${hata.message}). ${sure} ms sonra yeniden.`)50            await bekle(sure)51            bekleme = bekleme * 252        }53    }54}

• yanit.headers.get("retry-after") başlığı metin olarak verir, başlık yoksa null. Number("3") 3 olur; Number(null) ise, Ders 9'daki Number("") gibi, 0 verir. 0 yanlış sayılan bir değer olduğu için (Ders 12) başlık yoksa sure, artan beklemeye düşer.
• sure > 10000: servis "bir saat bekle" derse bir saat beklemeyiz. Sunucunu bekleyen bir ziyaretçi var; 10 saniyeden uzun beklemek yerine hatayı hemen yukarı ver ve ziyaretçiye "şu an olmuyor" de.
• Retry-After bazen saniye yerine bir tarih taşır (Wed, 21 Oct 2026 07:28:00 GMT gibi). Number ondan NaN üretir, NaN da yanlış sayılır; kodumuz o zaman da artan beklemeyle devam eder. Riot'un belgesi süreyi saniye olarak verdiğini söylüyor.

Üç saniye bekle ve deneme.js'i yeniden çalıştır:

PS C:\kod\sihirdar-api> node deneme.jsBuyur, taze veri1. istek: 87.344ms1. deneme olmadı (429 {"hata":"Çok sık istek attın"}). 3000 ms sonra yeniden.Buyur, taze veri2. istek: 3.012s1. deneme olmadı (429 {"hata":"Çok sık istek attın"}). 3000 ms sonra yeniden.Buyur, taze veri3. istek: 3.016s

Her 429'dan sonra servisin istediği kadar, 3 saniye beklendi ve ikinci deneme geçti. Sınıra uymak işe yarıyor ama yavaş: üç istek 6 saniyeden fazla sürdü. Asıl çözüm, aynı soruyu hiç sormamak.

#Önbellek: aynı soruyu iki kez sorma

Hava durumu 15 dakikada bir güncelleniyor; Open-Meteo'nun cevabındaki interval: 900'ü hatırla. Bir dakika içinde yüz ziyaretçi İstanbul'un havasını sorarsa Open-Meteo'ya yüz kez gitmek israf: cevap yüzünde de aynı. Cevabı bir kez alıp bir süre saklarsın, o süre içindeki her soruya saklananı verirsin. Ders 20'de tarayıcının CSS dosyalarını önbellekte tuttuğunu görmüştün; bu kez önbelleği kendin, sunucunda kuruyorsun.

Önce önbelleği ağsız, tek başına dene. onbellek.js dosyasına yaz; servis yerine sabit bir sürüm döndüren sahte bir fonksiyon kullanıyoruz:

1const onbellek = {}2 3async function onbellekli(anahtar, sureMs, is) {4    const kayit = onbellek[anahtar]5    if (kayit && Date.now() < kayit.bitis) {6        return kayit.veri7    }8    const veri = await is()9    onbellek[anahtar] = { veri: veri, bitis: Date.now() + sureMs }10    return veri11}12 13function bekle(ms) {14    return new Promise((resolve) => setTimeout(resolve, ms))15}16 17async function surumGetir() {18    console.log("Servise gidiliyor...")19    return "16.20.1"20}21 22console.log("1:", await onbellekli("surum", 1000, surumGetir))23console.log("2:", await onbellekli("surum", 1000, surumGetir))24await bekle(1100)25console.log("3:", await onbellekli("surum", 1000, surumGetir))

Servise gidiliyor...1: 16.20.12: 16.20.1Servise gidiliyor...3: 16.20.1

• onbellek düz bir obje (Ders 4): anahtar sorunun kendisi (bir adres gibi), değer { veri, bitis }.
• bitis, kaydın geçerliliğini yitireceği an: Date.now() + sureMs. Kayıt varsa ve şu an bitişten önceyse servise hiç gitmeden saklananı döndür.
• Yoksa işi yap, sonucu sakla, döndür. İş hata verirse await is() satırı fırlatır ve kayıt yazılmaz: hatalar önbelleğe girmez.

Çıktıda "Servise gidiliyor" iki kez geçiyor: ilk soruda ve 1,1 saniye sonra, kaydın 1 saniyelik ömrü dolunca. Arada gelen ikinci soru önbellekten cevaplandı.

Fonksiyon çalışıyor. onbellek objesini ve onbellekli fonksiyonunu disIstek.js'in sonuna taşı; dışarıdan kullanılacağı için başına export koy:

56const onbellek = {}57 58export async function onbellekli(anahtar, sureMs, is) {59    const kayit = onbellek[anahtar]60    if (kayit && Date.now() < kayit.bitis) {61        return kayit.veri62    }63    const veri = await is()64    onbellek[anahtar] = { veri: veri, bitis: Date.now() + sureMs }65    return veri66}

Şimdi 429 deneyini önbellekle tekrarla. deneme.js:

1import { jsonGetir, yenidenDene, onbellekli } from "./disIstek.js"2 3const adres = "http://localhost:4000/sinirli"4console.time("5 istek")5for (let i = 1; i <= 5; i++) {6    const veri = await onbellekli(adres, 10000, () => yenidenDene(() => jsonGetir(adres)))7    console.log(i, veri.mesaj)8}9console.timeEnd("5 istek")

PS C:\kod\sihirdar-api> node deneme.js1 Buyur, taze veri2 Buyur, taze veri3 Buyur, taze veri4 Buyur, taze veri5 Buyur, taze veri5 istek: 90.365ms

21:14:17 GET /sinirli

Beş soru, servise tek istek, hiç 429 yok ve toplam 90 milisaniye. Üç fonksiyon iç içe çalıştı: onbellekli önce kendi kaydına bakar, yoksa yenidenDene'yi çağırır, o da jsonGetir'i gerektiği kadar dener. Bir önceki denemeden hemen sonra çalıştırırsan ilk istek bir kez 429 alıp 3 saniye bekleyebilir; sonraki dördü yine önbellekten gelir.

#Ara sunucu: hepsi bir arada

Parçalar hazır. Şimdi tarayıcının soracağı uç noktayı yaz. Proje klasöründe app.js:

1import express from "express"2import { jsonGetir, yenidenDene, onbellekli } from "./disIstek.js"3 4const app = express()5const port = process.env.PORT || 30006 7app.use(express.static("public"))8 9app.get("/api/hava", async (req, res) => {10    const enlem = Number(req.query.enlem)11    const boylam = Number(req.query.boylam)12    if (!req.query.enlem || !req.query.boylam || Number.isNaN(enlem) || Number.isNaN(boylam)) {13        res.status(400).json({ hata: "enlem ve boylam sayı olmalı" })14        return15    }16    if (enlem < -90 || enlem > 90 || boylam < -180 || boylam > 180) {17        res.status(400).json({ hata: "enlem -90 ile 90, boylam -180 ile 180 arasında olmalı" })18        return19    }20    const parametreler = new URLSearchParams({21        latitude: enlem,22        longitude: boylam,23        current: "temperature_2m,wind_speed_10m",24        timezone: "auto"25    })26    const adres = "https://api.open-meteo.com/v1/forecast?" + parametreler27    const veri = await onbellekli(adres, 10 * 60 * 1000, () => {28        console.log("Open-Meteo'ya gidiliyor:", enlem, boylam)29        return yenidenDene(() => jsonGetir(adres))30    })31    res.json({32        sicaklik: veri.current.temperature_2m,33        ruzgar: veri.current.wind_speed_10m,34        saat: veri.current.time35    })36})37 38app.use((req, res) => {39    res.status(404).json({ hata: "Böyle bir yol yok" })40})41 42app.use((hata, req, res, next) => {43    console.log("Hata:", hata.name, hata.message)44    if (hata.name === "TimeoutError") {45        res.status(504).json({ hata: "Dış servis zamanında cevap vermedi" })46    } else if (hata.durum === 404) {47        res.status(404).json({ hata: "Dış serviste böyle bir kayıt yok" })48    } else if (hata.name === "DisServisHatasi" || hata.message === "fetch failed") {49        res.status(502).json({ hata: "Dış servise şu an ulaşılamıyor" })50    } else {51        res.status(500).json({ hata: "Sunucuda beklenmeyen bir hata oldu" })52    }53})54 55app.listen(port, (hata) => {56    if (hata) {57        throw hata58    }59    console.log(`Sihirdar API çalışıyor: http://localhost:${port}`)60})

• express.static("public"), public klasöründeki dosyaları olduğu gibi sunar (Ders 28); birazdan oraya bir sayfa koyacağız.
• Önce girdiyi doğrula ve gerekirse 400 dön (Ders 28): bozuk bir istek için dış servisin hakkını harcama. Sayıya çeviremediğin değer NaN olur; 41,01 gibi virgüllü bir sayı da 400 alır.
• Önbelleğin anahtarı, dış servisin tam adresi: aynı koordinat, aynı adres, aynı kayıt. Süre 10 * 60 * 1000, yani 10 dakika.
• Cevap olarak Open-Meteo'nun bütün JSON'unu değil, sayfanın ihtiyacı olan üç alanı gönderiyoruz. Open-Meteo bir gün alan adlarını değiştirirse yalnız bu satırlar değişir, sayfan değişmez.
• Express 5, async bir yolun içinden fırlayan hatayı kendiliğinden hata yakalayıcıya gönderir (Ders 28). Yakalayıcı, dış servis hatalarını ziyaretçiye uygun kodlara çevirir: zaman aşımı 504 Gateway Timeout, dış servisin 404'ü 404, öteki dış servis hataları 502 Bad Gateway. Bunlar Ders 26'da "sunucu ya da arkasındaki servis cevap veremiyor" diye gördüğün kodlar. Ayrıntıyı yalnız sunucunun terminaline yaz; ziyaretçiye dış servisin ham hatasını gönderme.

Sunucuyu ilk terminalde başlat. Sahte servis ikinci terminalde açık kalsın; istekleri terminal panelindeki + ile açacağın üçüncü bir terminalden at:

PS C:\kod\sihirdar-api> npm run dev > sihirdar-api@1.0.0 dev> node --watch --env-file=.env app.js Sihirdar API çalışıyor: http://localhost:3000

PS C:\kod\sihirdar-api> curl.exe -i "http://localhost:3000/api/hava?enlem=41.01&boylam=28.98"HTTP/1.1 200 OKX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 56ETag: W/"38-igILVEgswUcNhd7krkPD3cbTwe8"Date: Sun, 11 Oct 2026 18:15:18 GMTConnection: keep-aliveKeep-Alive: timeout=5 {"sicaklik":20.9,"ruzgar":1.9,"saat":"2026-10-11T21:15"}PS C:\kod\sihirdar-api> curl.exe "http://localhost:3000/api/hava?enlem=41.01&boylam=28.98"{"sicaklik":20.9,"ruzgar":1.9,"saat":"2026-10-11T21:15"}PS C:\kod\sihirdar-api> curl.exe "http://localhost:3000/api/hava?enlem=41,01&boylam=28,98"{"hata":"enlem ve boylam sayı olmalı"}PS C:\kod\sihirdar-api> curl.exe "http://localhost:3000/api/hava?enlem=95&boylam=28.98"{"hata":"enlem -90 ile 90, boylam -180 ile 180 arasında olmalı"}PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/yok{"hata":"Böyle bir yol yok"}

Sihirdar API çalışıyor: http://localhost:3000Open-Meteo'ya gidiliyor: 41.01 28.98

İki hava isteği, Open-Meteo'ya tek gidiş: ikincisi önbellekten geldi. Bozuk girdiler dış servise hiç ulaşmadı.

#Dış servis çökerse

Open-Meteo'nun çöktüğünü taklit et: app.js'te adres satırını geçici olarak sahte servisin yavaş yoluyla değiştir ve kaydet. --watch sunucuyu yeniden başlatır, önbellek de boşalır:

26    const adres = "http://localhost:4000/yavas"

PS C:\kod\sihirdar-api> curl.exe -i "http://localhost:3000/api/hava?enlem=41.01&boylam=28.98"HTTP/1.1 504 Gateway TimeoutX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 48ETag: W/"30-tYCZzkU0XNA23o5TYxH4lvv5nvI"Date: Sun, 11 Oct 2026 18:15:47 GMTConnection: keep-aliveKeep-Alive: timeout=5 {"hata":"Dış servis zamanında cevap vermedi"}

Open-Meteo'ya gidiliyor: 41.01 28.981. deneme olmadı (The operation was aborted due to timeout). 500 ms sonra yeniden.2. deneme olmadı (The operation was aborted due to timeout). 1000 ms sonra yeniden.Hata: TimeoutError The operation was aborted due to timeout

Cevap 7,6 saniyede geldi: üç deneme, her biri 2 saniyelik süre sınırıyla, aralarda da 1,5 saniye bekleme. Ziyaretçi için uzun bir süre. Deneme sayısını, süre sınırını ve beklemeyi seçerken bu toplamı hep hesapla. Adresi bir de kimsenin dinlemediği bir porta çevir, http://localhost:4001/:

Open-Meteo'ya gidiliyor: 41.01 28.981. deneme olmadı (fetch failed). 500 ms sonra yeniden.2. deneme olmadı (fetch failed). 1000 ms sonra yeniden.Hata: TypeError fetch failed

Bu kez curl 502 Bad Gateway ve {"hata":"Dış servise şu an ulaşılamıyor"} aldı. Denemeden sonra adres satırını eski hâline, Open-Meteo'ya geri getir.

#Tarayıcıdan sor

Son parça tarayıcı tarafı. Proje klasöründe public adında bir klasör aç ve içine index.html koy:

1<!doctype html>2<html lang="tr">3<head>4    <meta charset="utf-8">5    <meta name="viewport" content="width=device-width, initial-scale=1">6    <title>Turnuva günü</title>7</head>8<body>9    <h1>Turnuva günü: İstanbul</h1>10    <p id="hava">Hava durumu yükleniyor...</p>11    <script>12        async function havayiGoster() {13            const kutu = document.querySelector("#hava")14            try {15                const yanit = await fetch("/api/hava?enlem=41.01&boylam=28.98")16                const veri = await yanit.json()17                if (!yanit.ok) {18                    kutu.textContent = veri.hata19                    return20                }21                kutu.textContent = `${veri.sicaklik} °C, rüzgâr ${veri.ruzgar} km/sa (ölçüm: ${veri.saat})`22            } catch (hata) {23                kutu.textContent = "Sunucuya ulaşılamadı"24            }25        }26 27        havayiGoster()28    </script>29</body>30</html>

fetch'teki adres / ile başlıyor ve alan adı yok: istek, sayfanın geldiği sunucuya, yani senin ara sunucuna gider (Ders 28'deki fetch("/api/sampiyonlar") gibi). Sayfa ile API aynı sunucudan geldiği için CORS'a da takılmaz. Tarayıcıda localhost:3000 adresini aç:

localhost:3000

F12 ile geliştirici araçlarını aç, Network sekmesine geç ve sayfayı yenile. İstek listesinde sayfanın kendisi ve hava?enlem=41.01&boylam=28.98 var; tarayıcı sekme simgesi için favicon.ico'yu da isteyebilir, sunucun ona 404 döner.

Hepsi localhost:3000'e gidiyor; Open-Meteo'nun adı hiçbir istekte geçmiyor. Tarayıcı dış servisi hiç görmedi. Anahtar isteyen bir servis olsaydı anahtarı da görmeyecekti.

#Riot için uç nokta

Aynı kalıpla Riot'un hesap uç noktasını da sarabilirsin. Bu yol anahtar isteyecek; önce, anahtar okunmadıysa sunucu açılırken uyaran bir denetim koy. app.js'te const port satırının altına ekle:

7if (!process.env.RIOT_API_KEY) {8    console.log("Uyarı: RIOT_API_KEY yok. --env-file=.env ile mi başlattın?")9}

Sonra /api/hava yolunun hemen altına, 404 yakalayıcısından önce yeni yolu yaz:

42app.get("/api/hesap/:ad/:etiket", async (req, res) => {43    const adres = "https://europe.api.riotgames.com/riot/account/v1/accounts/by-riot-id/"44        + encodeURIComponent(req.params.ad) + "/" + encodeURIComponent(req.params.etiket)45    const hesap = await onbellekli(adres, 60 * 60 * 1000, () => {46        console.log("Riot'a gidiliyor:", adres)47        return yenidenDene(() => jsonGetir(adres, { "X-Riot-Token": process.env.RIOT_API_KEY }))48    })49    res.json({ ad: hesap.gameName, etiket: hesap.tagLine, puuid: hesap.puuid })50})

• Uyarı satırı, --env-file unutulduğunda Forbidden hatasıyla uğraşmak yerine sorunu ilk saniyede söyler. Program yine açılır; /api/hava'nın anahtara ihtiyacı yok.
• Tarayıcı Kırmızı Ejder adını K%C4%B1rm%C4%B1z%C4%B1%20Ejder diye kodlayıp gönderir; Express req.params.ad'ı çözüp yeniden Kırmızı Ejder yapar. Riot'a giderken encodeURIComponent ile yeniden kodluyoruz.
• Önbellek süresi bir saat. Bir hesabın PUUID'si hiç değişmez; oyuncu Riot ID'sini değiştirirse eski kayıt en geç bir saat içinde süresi dolup gider.
• Riot'un 404'ü ("böyle bir Riot ID yok") hata yakalayıcıda 404 olarak tarayıcıya geçer. Anahtar sorunları (401, 403) ise 502 olur: ziyaretçinin değil, senin sunucunun sorunu.

Uydurma anahtarla dene. Tarayıcıda localhost:3000/api/hesap/Kırmızı Ejder/TR1 adresini de açabilirsin; tarayıcı kodlamayı kendisi yapar:

PS C:\kod\sihirdar-api> curl.exe -i http://localhost:3000/api/hesap/K%C4%B1rm%C4%B1z%C4%B1%20Ejder/TR1HTTP/1.1 502 Bad GatewayX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 47ETag: W/"2f-vrKOvbM2FjvFULH6H6aBJdxVGDA"Date: Sun, 11 Oct 2026 18:16:27 GMTConnection: keep-aliveKeep-Alive: timeout=5 {"hata":"Dış servise şu an ulaşılamıyor"}

Riot'a gidiliyor: https://europe.api.riotgames.com/riot/account/v1/accounts/by-riot-id/K%C4%B1rm%C4%B1z%C4%B1%20Ejder/TR1Hata: DisServisHatasi 401 {"status":{"message":"Unknown apikey","status_code":401}}

Riot 401 dedi; ziyaretçi yalnız 502 ve genel bir cümle gördü, ayrıntı senin terminalinde kaldı. Geçerli bir anahtarla ve var olan bir Riot ID ile cevap {"ad":"...","etiket":"TR1","puuid":"..."} biçiminde gelir.

Şimdi uyarıyı gör. İlk terminalde sunucuyu Ctrl+C ile durdur ve bu kez --env-file olmadan başlat:

PS C:\kod\sihirdar-api> node app.jsUyarı: RIOT_API_KEY yok. --env-file=.env ile mi başlattın?Sihirdar API çalışıyor: http://localhost:3000

Denedikten sonra yine Ctrl+C ile durdur ve npm run dev ile yeniden başlat. Sunucu açıkken ikinci bir kopyayı başka bir terminalde başlatırsan 3000 numaralı kapı dolu olduğu için EADDRINUSE ile durur (Ders 28).

#Görevler

Görevleri sihirdar-api klasöründe yap. Sunucu görevlerinde npm run dev açık kalsın, istekleri ayrı bir terminalden curl.exe ile at ve hem cevaba hem sunucunun terminaline bak. Önce kendin dene, takılırsan ipuçlarını sırayla aç.

Yarın (2026-10-12) Ankara: en düşük 11.4 °C, en yüksek 23.5 °C

1const parametreler = new URLSearchParams({2    latitude: "39.93",3    longitude: "32.86",4    daily: "temperature_2m_max,temperature_2m_min",5    forecast_days: "2",6    timezone: "auto"7})8const yanit = await fetch("https://api.open-meteo.com/v1/forecast?" + parametreler)9const veri = await yanit.json()10 11const gun = veri.daily.time[1]12const enDusuk = veri.daily.temperature_2m_min[1]13const enYuksek = veri.daily.temperature_2m_max[1]14console.log(`Yarın (${gun}) Ankara: en düşük ${enDusuk} °C, en yüksek ${enYuksek} °C`)

Yarın (2026-10-12) Ankara: en düşük 11.4 °C, en yüksek 23.5 °C

En yeni sürüm: 16.20.1

1const adres = "https://ddragon.leagueoflegends.com/api/versions.json"2 3try {4    const yanit = await fetch(adres, { signal: AbortSignal.timeout(1500) })5    if (!yanit.ok) {6        throw new Error("Durum kodu " + yanit.status)7    }8    const surumler = await yanit.json()9    console.log("En yeni sürüm: " + surumler[0])10} catch (hata) {11    if (hata.name === "TimeoutError") {12        console.log("Data Dragon 1,5 saniyede cevap vermedi")13    } else {14        console.log("Sürüm alınamadı: " + hata.message)15    }16}

En yeni sürüm: 16.20.1

1. denemeden sonra 500 ms2. denemeden sonra 1000 ms3. denemeden sonra 2000 ms4. denemeden sonra 2000 ms5. denemeden sonra 2000 ms

1function beklemeSuresi(deneme) {2    let sure = 5003    for (let i = 1; i < deneme; i++) {4        sure = sure * 25    }6    return Math.min(sure, 2000)7}8 9for (let deneme = 1; deneme <= 5; deneme++) {10    console.log(`${deneme}. denemeden sonra ${beklemeSuresi(deneme)} ms`)11}

1. denemeden sonra 500 ms2. denemeden sonra 1000 ms3. denemeden sonra 2000 ms4. denemeden sonra 2000 ms5. denemeden sonra 2000 ms

app.get("/api/surum", async (req, res) => {    const adres = "https://ddragon.leagueoflegends.com/api/versions.json"    const surumler = await onbellekli(adres, 60 * 60 * 1000, () => {        console.log("Data Dragon'a gidiliyor")        return yenidenDene(() => jsonGetir(adres))    })    res.json({ surum: surumler[0] })})

PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/surum{"surum":"16.20.1"}PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/surum{"surum":"16.20.1"}PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/surum{"surum":"16.20.1"}

Sihirdar API çalışıyor: http://localhost:3000Data Dragon'a gidiliyor

1app.get("/gizli", (req, res) => {2    if (req.get("X-Sahte-Anahtar") !== "lux-123") {3        res.status(401).json({ hata: "Anahtar yanlış" })4        return5    }6    res.json({ mesaj: "Anahtar doğru, hoş geldin" })7})

{"mesaj":"Anahtar doğru, hoş geldin"}

app.get("/api/gizli", async (req, res) => {    const veri = await jsonGetir("http://localhost:4000/gizli", {        "X-Sahte-Anahtar": process.env.SAHTE_ANAHTAR    })    res.json({ mesaj: veri.mesaj })})

PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/gizli{"mesaj":"Anahtar doğru, hoş geldin"}PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/gizli{"hata":"Dış servise şu an ulaşılamıyor"}

Change detected in 'C:\\kod\\sihirdar-api\\.env'Restarting 'app.js'Sihirdar API çalışıyor: http://localhost:3000Hata: DisServisHatasi 401 {"hata":"Anahtar yanlış"}

async function havaGetir(enlem, boylam) {    const parametreler = new URLSearchParams({        latitude: enlem,        longitude: boylam,        current: "temperature_2m,wind_speed_10m",        timezone: "auto"    })    const adres = "https://api.open-meteo.com/v1/forecast?" + parametreler    const veri = await onbellekli(adres, 10 * 60 * 1000, () => {        console.log("Open-Meteo'ya gidiliyor:", enlem, boylam)        return yenidenDene(() => jsonGetir(adres))    })    return {        sicaklik: veri.current.temperature_2m,        ruzgar: veri.current.wind_speed_10m,        saat: veri.current.time    }} const sehirler = {    istanbul: { enlem: 41.01, boylam: 28.98 },    ankara: { enlem: 39.93, boylam: 32.86 },    izmir: { enlem: 38.42, boylam: 27.14 }} app.get("/api/sehir/:ad", async (req, res) => {    const anahtar = req.params.ad.toLocaleLowerCase("tr")    if (!Object.keys(sehirler).includes(anahtar)) {        res.status(404).json({ hata: `Bu şehri tanımıyorum: ${req.params.ad}` })        return    }    const sehir = sehirler[anahtar]    const hava = await havaGetir(sehir.enlem, sehir.boylam)    res.json({ sehir: anahtar, ...hava })})

PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/sehir/istanbul{"sehir":"istanbul","sicaklik":20.8,"ruzgar":2.2,"saat":"2026-10-11T21:30"}PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/sehir/%C4%B0ZM%C4%B0R{"sehir":"izmir","sicaklik":20.5,"ruzgar":0.4,"saat":"2026-10-11T21:30"}PS C:\kod\sihirdar-api> curl.exe -i http://localhost:3000/api/sehir/IZMIRHTTP/1.1 404 Not FoundX-Powered-By: ExpressContent-Type: application/json; charset=utf-8Content-Length: 41ETag: W/"29-xpe4di0UEkFrNaNE34KPsoztPLU"Date: Sun, 11 Oct 2026 18:30:36 GMTConnection: keep-aliveKeep-Alive: timeout=5 {"hata":"Bu şehri tanımıyorum: IZMIR"}PS C:\kod\sihirdar-api> curl.exe http://localhost:3000/api/sehir/constructor{"hata":"Bu şehri tanımıyorum: constructor"}

#Kendini sına

SyntaxError: Unexpected token '<', "<!doctype "... is not valid JSON    at JSON.parse (<anonymous>)    at parseJSONFromBytes (node:internal/deps/undici/undici:4394:19)

#Kayıt noktası

Projeyi Git'e kaydet. sihirdar-api yeni bir proje klasörü olduğu için önce git init. Sunucuları durdurmana gerek yok; komutları üçüncü terminalde yaz:

Bir sonraki derste kendi API'nin kapısına kilit takacaksın: kullanıcı girişi, şifreleri güvenle saklamak, korunan yollar ve en sık güvenlik açıkları. Ders 31: Kimlik doğrulama ve güvenlik temelleri.