API entegrasyonlarında en sık yapılan hata, sağlayıcı anahtarını hızlıca çalıştırmak uğruna güvenlik sınırını belirsiz bırakmaktır. Bir anahtarın frontend bundle içinde görünmesi, public repository'e commit edilmesi veya her kullanıcıya aynı kotayla açılması küçük bir hata gibi görünür; sonuçta kota tüketimi, veri sızıntısı veya hesap engeli doğurabilir.
Bu rehber, API Deposu'ndaki TCMB EVDS, Alpha Vantage, Finnhub ve Google Gemini API gibi anahtar kullanan entegrasyonları düşünerek yazıldı. Ama prensipler neredeyse tüm üçüncü taraf API'ler için geçerlidir.
Anahtarı tarayıcıya göndermeyin
Gizli API anahtarı kullanıcı tarayıcısına gidiyorsa artık gizli değildir. JavaScript bundle, network isteği, source map, localStorage veya mobil uygulama paketi içindeki anahtarlar çıkarılabilir. Bu yüzden provider anahtarı backend route, server action veya ayrı bir backend servisinde tutulmalıdır.
Backend boundary sadece anahtarı saklamak için değil, isteği doğrulamak için de gerekir. Kullanıcının hangi endpoint'i çağırabileceğini, hangi parametreleri gönderebileceğini ve ne kadar kota kullanabileceğini burada kontrol edersiniz. Aksi halde kendi uygulamanız sağlayıcı API'si için açık proxy'ye dönüşebilir.
Rate limit modelini siz kurun
Sağlayıcının rate limitine güvenmek yeterli değildir. Alpha Vantage veya Finnhub gibi API'lerde limit aşımı ürün deneyimini doğrudan bozar. Kullanıcı sayısı arttığında tek sağlayıcı anahtarının kotası herkes tarafından paylaşılır.
Bu yüzden kendi rate limit anahtarınızı belirleyin: kullanıcı ID, tenant ID, IP, session veya özellik bazlı limit. Kimliği doğrulanmış kullanıcıyla anonim trafik aynı kotayı kullanmamalıdır. Pahalı endpoint'ler için ayrı limit, arama/autocomplete gibi yoğun endpoint'ler için daha kısa pencere tanımlanmalıdır.
Hata normalizasyonu
Her sağlayıcı hata yanıtını farklı döndürür. Biri 429 verir, diğeri 403 ile kota hatası döner, başka biri JSON içinde hata mesajı taşır. UI'ın bu farkları bilmesi kötü bir mimaridir. Backend tarafında sağlayıcı hatalarını kendi hata modelinize çevirin.
Örneğin RATE_LIMITED, INVALID_API_KEY, PROVIDER_UNAVAILABLE, BAD_PROVIDER_RESPONSE gibi sınıflar UI için yeterlidir. Böylece kullanıcıya anlaşılır mesaj gösterilir, loglarda sağlayıcı detayı korunur ve ileride sağlayıcı değişirse frontend etkilenmez.
Secret rotation ve sızıntı planı
Anahtarın hiç sızmayacağını varsaymayın. Her entegrasyon için anahtar nerede tutuluyor, kim erişebiliyor, nasıl rotate ediliyor ve sızıntı olursa hangi adımlar izleniyor bilinmelidir. GitHub secret scanning, environment variable yönetimi ve sağlayıcı panelindeki key revoke akışı pratikte hayat kurtarır.
Anahtarı rotate ederken eski ve yeni anahtarın kısa süre birlikte çalışabileceği bir dağıtım planı gerekir. Özellikle birden fazla servis veya Vercel environment kullanıyorsanız Production, Preview ve local .env değerlerinin ayrımı açık tutulmalıdır.
Cache güvenliğin parçasıdır
Cache sadece performans değil, kota koruma aracıdır. Aynı TCMB EVDS serisini veya aynı piyasa verisini her kullanıcı için tekrar çekmek yerine backend cache kullanmak hem hız kazandırır hem sağlayıcı kotasını korur. Ancak kullanıcıya özel veya gizli veriler yanlışlıkla global cache'e konmamalıdır.
Cache anahtarında kullanıcıya özel parametre varsa bunu açıkça modelleyin. Public veri ve private veri aynı cache katmanında karışmamalıdır. API güvenliği çoğu zaman bu küçük sınırların netliğine bağlıdır.
Log ve gözlemleme
Güvenli API entegrasyonu log olmadan eksik kalır. Her sağlayıcı çağrısında endpoint adı, status code, süre, normalize hata kodu ve rate limit sonucu kaydedilmelidir. Ancak secret, token, kişisel veri veya tam request body loglara yazılmamalıdır.
Bu metrikler olmadan kötüye kullanım ile normal trafik artışını ayırmak zorlaşır. Bir kullanıcı kısa sürede yüzlerce pahalı istek atıyorsa bunu sağlayıcı faturasında değil, kendi alarmınızda görmelisiniz. Aynı şekilde 429 oranı artıyorsa cache veya kota stratejisi yeniden düzenlenmelidir.
En iyi pratik, her yeni provider için küçük bir entegrasyon checklist'i tutmaktır: secret nerede, rotate nasıl yapılır, rate limit nedir, hata modeli nasıl normalize edilir, cache uygun mu ve hangi loglar tutulur? Bu checklist kod kadar önemlidir.
İlgili API Deposu kayıtları
Kaynaklar
Sik Sorulan Sorular
›API anahtarı frontend kodunda tutulabilir mi?
Genel kural hayırdır. Kullanıcı tarayıcısına giden her anahtar görünür kabul edilmelidir; gizli sağlayıcı anahtarları backend veya server-side boundary arkasında tutulmalıdır.
›Rate limit sadece sağlayıcıya mı bırakılmalı?
Hayır. Sağlayıcı limiti son savunma hattıdır. Uygulama kendi kullanıcı, IP, tenant veya özellik bazlı limitlerini backend tarafında uygulamalıdır.
›API anahtarı sızarsa ne yapılmalı?
Anahtarı hemen revoke/rotate edin, loglarda kötüye kullanım arayın, etkilenen istekleri inceleyin ve yeni anahtarı daha dar izinlerle yayınlayın.
›Ücretsiz API'lerde güvenlik daha mı az önemlidir?
Hayır. Ücretsiz API anahtarı da kötüye kullanım, kota tüketimi, maliyet artışı ve servis engeli yaratabilir. Ücretsiz olması güvenlik sınırlarını kaldırmaz.