API Anahtarlarını, Kotaları ve Kullanım Analitiğini Yöneten Bir Web Uygulaması İnşa Edin

Ne İnşa Ediyorsunuz ve Kimler İçin\n\nAPI ile bunu kullananların arasında duran bir web uygulaması inşa ediyorsunuz. Görevi API anahtarları vermek, bu anahtarların nasıl kullanılacağını kontrol etmek ve ne olduğunu açıklamak—hem geliştiriciler hem de geliştirici olmayanlar için yeterince açık biçimde.\n\nEn azından üç pratik soruya yanıt verir:\n\n- API'yi kim çağırıyor? (Hangi müşteri, hangi uygulama, hangi anahtar)\n- Ne kadar kullanmalarına izin veriliyor? (Kotalar, rate limitler, plan kuralları)\n- Gerçekte ne kadar kullandılar? (Güvenilir ölçüm ve analiz)\n\nPortal ve yönetici UI'sında hızlı ilerlemek istiyorsanız, Koder.ai gibi araçlar üretim seviyesi bir başlangıcı (React frontend + Go backend + PostgreSQL) tek seferde prototipleyip yayınlamanıza yardımcı olabilir; buna rağmen kaynak kodu dışa aktarma, snapshot/rollback ve dağıtım/host etme ile tam kontrolu korursunuz.\n\n### Kim Kullanır\n\nAnahtar yönetim uygulaması sadece mühendisler için değildir. Farklı roller, farklı hedeflerle gelir:\n\n- Yöneticiler / platform sahipleri politikalar (limitler, erişim seviyeleri) oluşturmak, olayları hızlı çözmek ve birçok müşteri arasında kontrolü sürdürmek ister.\n- Geliştiriciler (müşterileriniz veya dahili ekipler) kendi kendine anahtar oluşturmak, basit dokümanlar ve bir şey bozulduğunda (“Neden 429 alıyorum?”) hızlı cevaplar ister.\n- Finans ve destek ekipleri kullanım geçmişi, müşteri düzeyinde özetler ve faturaları, kredi veya plan yükseltmelerini destekleyecek veriler ister—ham logları okumadan.\n\n### İhtiyaç Duyacağınız Temel Modüller\n\nBaşarılı uygulamalar genellikle birkaç çekirdek modülde birleşir:\n\n- Anahtarlar: anahtar oluşturma, ad/veri etiketi, izinleri kapsamlandırma, döndürme (rotate), iptal etme ve son kullanım bilgisini görüntüleme.\n- Kotalar ve rate limiting: anahtar, müşteri veya endpoint başına limit tanımlama ve tutarlı şekilde uygulama.\n- Kullanım ölçümü: istek olaylarını (veya özetlerini) yakalama ve günlük/aylık kullanıma toplama.\n- Analitik: kullanım trendlerini, en çok kullanılan endpointleri, hataları ve throttling'i açıklayan panolar.\n- Uyarılar: kullanım arttığında, kotalar neredeyse dolduğunda, anahtar kötüye kullanıldığında veya hatalar çoğaldığında bildirim gönderme.\n\n### Kapsam: basit başlayın, sonra genişletin\n\nGüçlü bir MVP, anahtar verme + temel limitler + net kullanım raporlaması üzerine odaklanır. Otomatik plan yükseltmeleri, faturalama iş akışları, proration ve karmaşık sözleşme şartları gibi gelişmiş özellikler, ölçüm ve uygulamaya güven kazandıktan sonra eklenebilir.\n\nİlk sürüm için pratik bir “kuzey yıldızı”: birinin anahtar oluşturmasını, limitlerini anlamasını ve destek bileti açmadan kullanımını görmesini kolaylaştırmak.\n\n## Gereksinimler Kontrol Listesi (MVP vs Sonrası)\n\nKoda başlamadan önce ilk sürüm için “tamam”ın ne anlama geldiğini belirleyin. Bu tür bir sistem hızla büyür: faturalama, denetimler ve kurumsal güvenlik beklediğinizden erken ortaya çıkar. Net bir MVP sizi hareket ettirir.\n\n### MVP: gerçek değer yaratan asgari özellikler\n\nEn azından kullanıcılar şunları yapabilmeli:\n\n- API anahtarları oluşturup iptal edebilme (isim/etiket ve isteğe bağlı sona erme ile)\n- Kotaları ayarlama (örn. istek/gün veya istek/ay) anahtar veya proje başına\n- Rate limiting uygulama (örn. istek/dakika) API'nizi korumak için\n- Kullanım grafiklerini görme (basit günlük toplamlar, en çok kullanılan anahtarlar ve hata oranları)\n- Temel denetim olaylarını takip etme (anahtar oluşturuldu/iptal edildi, kota değişti) destek ve hesap verebilirlik için\n\nEğer güvenli şekilde anahtar veremiyor, onu sınırlandıramıyor ve ne yaptığını kanıtlayamıyorsanız, hazır değil demektir.\n\n### Fonksiyonel Olmayan Gereksinimler (önceden kararlaştırılmalı)\n\n- Performans: event düşürmeden ölçüm yapmanız gereken saniyedeki maksimum istek sayısı nedir?\n- Güvenilirlik: “hiçbir zaman kullanım olayını kaybetmeme” mi gerekiyor yoksa “sonunda doğru” kabul edilebilir mi?\n- Veri saklama: ham olayları vs toplanmış toplamları ne kadar saklarsınız (örn. ham 7 gün, toplu 13 ay)?\n\n### Kiracı modeli: tek org vs çok kiracılı\n\nErken seçin:\n\n- Tek org: daha hızlı inşa, daha az rol/izin kenar durumu.\n- Çok kiracılı SaaS: kiracı izolasyonu, kiracı başına kotalar ve yönetici rolleri gerektirir.\n\n### Sonrası için planlamaya değer özellikler\n\nDöndürme akışları, webhook bildirimleri, faturalama dışa aktarımları, SSO/SAML, endpoint başına kotalar, anomali tespiti ve daha zengin denetim kayıtları.\n\n### Başarı ölçütleri (ölçülebilir yapın)\n\n- Anahtar verme süresi: örn. kayıt sonrası 2 dakika altında ilk anahtar\n- Ölçüm doğruluğu: örn. gateway sayımları ile toplamlar arasında %0.5'ten az fark\n- Destek yükü: “neden engellendim?” ticket’larında azalma; net kota/rate-limit açıklamaları\n\n## Yüksek Seviye Mimari Seçenekleri\n\nMimari tercihiniz bir soruyla başlamalı: erişimi ve limitleri nerede uygularsınız? Bu karar gecikmeyi, güvenilirliği ve ne kadar hızlı gönderebileceğinizi etkiler.\n\n### Seçenek 1: Bir API gateway'de uygulama\n\nBir API gateway (yönetilen veya self-hosted) API anahtarlarını doğrulayabilir, rate limit uygulayabilir ve kullanım olayları yayabilir, istekler servislerinize ulaşmadan önce.\n\nBu, birden çok backend servisi olduğunda, tutarlı politikalar gerektiğinde veya uygulama kodunun dışına enforcement almak istediğinizde iyi bir eşleşme. Dezavantajı: gateway konfigürasyonu kendi “ürün”ü haline gelebilir ve hata ayıklama iyi izleme gerektirebilir.\n\n### Seçenek 2: Bir reverse proxy'de uygulama\n\nBir reverse proxy (örn. NGINX/Envoy) pluginler veya dış auth hook'lar ile anahtar kontrolleri ve rate limiting yapabilir.\n\nHafif bir edge katmanı istediğinizde iyi çalışır, ancak iş kurallarını (planlar, kiracı başına kotalar, özel durumlar) modellemek destek servisleri olmadan zorlaşabilir.\n\n### Seçenek 3: Uygulama ara katmanında uygulama\n\nKontrolleri API uygulamanızda (middleware) koymak genellikle MVP için en hızlısıdır: tek kod tabanı, tek deploy, daha basit lokal test.\n\nServis sayısını artırdıkça zorlaşabilir—politik tutarsızlığı ve kopyalanmış mantık yaygındır—bu yüzden ileride ortak bir bileşen veya edge katmanına çıkarma planlayın.\n\n### Ayrımları erken yapın\n\nKüçük başlasanız bile sınırları net tutun:\n\n- Auth (anahtar geçerli mi?), kota/rate limit (şimdi izin veriliyor mu?), ölçüm (ne oldu kaydet), analitik UI (göster).\n\n### Senkron vs asenkron takip\n\nÖlçüm için istek yolunda ne olması gerektiğine karar verin:\n\n- Senkron: cevaplamadan önce sayaç arttırma (doğru enforcement, daha yüksek gecikme).\n- Asenkron: olayları bir kuyruğa/loga yayınlama (daha hızlı istekler, raporlar için nihai tutarlılık).\n\n### Ölçek için plan: sıcak vs soğuk yollar\n\nRate limit kontrolleri sıcak yoldir (düşük gecikme, bellek/içinde/Redis optimize edin). Raporlar ve panolar soğuk yoldur (esnek sorgular ve toplu agregasyon optimize edin).\n\n## Anahtarlar, Kotalar ve Kullanım için Veri Modeli\n\nİyi bir veri modeli üç kaygıyı ayırır: erişimi kim yönetiyor, hangi limitler uygulanıyor, ve gerçekte ne oldu. Bunu doğru yaparsanız, döndürme, panolar ve faturalama basitleşir.\n\n### Çekirdek varlıklar (ilk gün ihtiyacı)\n\nEn azından şu tabloları/modellemeyi yapın:\n\n- Organization: kiracı sınırı (faturalama sahibi, üyeler).\n- Project/App: anahtarlar ve ayarlar için kapsayıcı (genellikle bir API istemcisine karşılık gelir).\n- API Key: bir kimlik bilgisinin meta verisi (isim, durum, created_at, last_used_at).\n- Plan: limitler ve özellikler paketi (örn. Free, Pro).\n- Quota: belirli limit kuralları (örn. 10k requests/day, 60 req/min).\n- Usage Event: kullanımın ham kaydı (timestamp, project_id, endpoint, status code, units).\n\n### Meta verileri gizli bilgiden ayrı saklayın\n\nHam API tokenlarını asla saklamayın. Sadece şunları saklayın:\n\n- Görüntüleme/arama için bir anahtar öneki (ilk 6–8 karakter)\n- Doğrulama için bir verifier (genellikle SHA-256 veya HMAC-SHA-256 ile sunucu tarafı pepper)\n- Opsiyonel: scope'lar, environment (prod/sandbox) ve expires_at\n\nBöylece “Key: ab12cd…” gösterebilir, gerçek sırrı geri döndürülemez halde tutarsınız.\n\n### Denetlenebilirlik zorunludur\n\nErken denetim tabloları ekleyin: KeyAudit ve AdminAudit (veya tek bir AuditLog) şu bilgileri yakalayan:\n\n- actor_id (kullanıcı/servis), action, target_type/id\n- before/after (kota düzenlemeleri için)\n- ip/user_agent, timestamp\n\nMüşteri “anahtarımı kim iptal etti?” diye sorduğunda cevap verebilmelisiniz.\n\n### Zaman pencereleri ve sayaçlar\n\nKotaları açık pencerelerle modelleyin: per_minute, per_hour, per_day, per_month.\n\nSayaçları ayrı bir tabloda (UsageCounter) (project_id, window_start, window_type, metric) şeklinde saklayın. Bu resetleri öngörülebilir kılar ve analitik sorgularını hızlı tutar.\n\nPortal görünümleri için Usage Events'i günlük toplamlara agregate edip daha derin detay için /blog/usage-metering referansı verebilirsiniz.\n\n## Kimlik Doğrulama, Yetkilendirme ve Roller\n\nÜrününüz API anahtarlarını ve kullanımı yönetiyorsa uygulamanızın erişim kontrolü tipik bir CRUD panosundan daha sıkı olmalıdır. Net bir rol modeli ekipleri üretken tutar ve “herkes admin” olmaktan kaçınır.\n\n### Gerçek ekiplerle eşleşen rol tasarımı\n\nHer organizasyona (kiracıya) küçük bir rol setiyle başlayın:\n\n- Owner: tam kontrol, fatura sahibi, org ayarlarını yönetme ve org'u silebilme.\n- Admin: kullanıcıları, projeleri, anahtarları, kotaları ve güvenlik ayarlarını yönetir.\n- Developer: atandığı projeler için anahtar oluştur/döndürme, kullanımı görüntüleme; fatura veya org-genel güvenliği değiştiremez.\n- Read-only: anahtarları (maskeli), kotaları ve analitiği görüntüleyebilir.\n- Finance: faturaları/kullanım maliyet raporlarını görüntüleyebilir ve veri dışa aktarabilir; anahtar yönetemez.\n\nİzinleri açık tutun (örn. keys:rotate, quotas:update) böylece yeni özellik eklerken rolleri yeniden tanımlamak zorunda kalmazsınız.\n\n### İnsanlar için güvenli giriş\n\nSadece kullanıcı adı/parola kullanmayın; mümkünse OAuth/OIDC destekleyin. SSO isteğe bağlı, ancak MFA sahipler/i yöneticiler için zorunlu ve herkese şiddetle tavsiye edilir.\n\nOturum korumaları ekleyin: kısa ömürlü erişim tokenleri, refresh token rotasyonu ve cihaz/oturum yönetimi.\n\n### Koruduğunuz API'ler için kimlik doğrulama\n\nVarsayılan olarak başlıkta API anahtarı sunun (örn. Authorization: Bearer <key> veya X-API-Key). İleri düzey müşteriler için opsiyonel HMAC signing (replay/tampering önler) veya JWT (kısa ömürlü, kapsamlı erişim için uygun) ekleyin. Bunları geliştirici portalınızda açıkça dokümante edin.\n\n### Kiracı izolasyonu: pazarlık konusu değil\n\nHer sorguda org_id uygulayın. Sadece UI filtrelerine güvenmeyin—veritabanı kısıtlamaları, satır düzeyi politikalar (varsa) ve servis katmanı kontrolleri uygulayın ve kiracılar arası erişimi denemek için testler yazın.\n\n## API Anahtar Yaşam Döngüsü: Oluştur, Döndür, İptal Et\n\nİyi bir anahtar yaşam döngüsü müşterileri üretken tutar ve bir sorun çıktığında riski hızlıca azaltmanızı sağlar. UI ve API'yı “mutlu yol”u bariz kılacak, daha güvenli seçenekleri (döndürme, sona erdirme) varsayılan yapacak şekilde tasarlayın.\n\n### Oluşturma: sadece bir string değil, niyeti yakalayın\n\nAnahtar oluşturma akışında bir isim (örn. “Prod server”, “Local dev”) ve anahtarın least-privilege olmasını sağlayacak scope/izinler isteyin.\n\nUygunsa, opsiyonel kısıtlamalar ekleyin: izin verilen originler (tarayıcı kullanımında) veya izin verilen IP'ler/CIDR (sunucu-sunucu için). Bunları isteğe bağlı tutun ve kilitlenme uyarıları gösterin.\n\nOluşturduktan sonra ham anahtarı yalnızca bir kez gösterin. Büyük bir “Kopyala” düğmesi ve kısa rehberlik sağlayın: “Bir gizli yöneticiye kaydedin. Biz tekrar gösteremeyiz.” doğrudan /docs sayfasına yönlendirmeler yapın.\n\n### Döndürme: rutin bir işlem olsun, bir olay değil\n\nDöndürme şu öngörülebilir adımları izlemeli:\n\n1. Aynı scope ve kısıtlamalara sahip yeni bir anahtar oluşturun.\n2. Entegrasyonu yeni anahtarı kullanacak şekilde deploy/güncelleyin.\n3. Trafiğin aktığını doğrulayın.\n4. Eski anahtarı iptal edin.\n\nUI'da bir “Rotate” eylemi sağlayın: yedek bir anahtar oluşturur ve eski anahtarı “Pending revoke” olarak işaretleyerek temizlik yapılmasını teşvik eder.\n\n### İptal ve sona erme: anlık ve planlı\n\nİptal anahtarı hemen devre dışı bırakmalı ve kim, neden yaptığı loglanmalı.\n\nAyrıca planlı sona erme (örn. 30/60/90 gün) ve geçici yükleniciler veya denemeler için manuel “expires on” tarihleri destekleyin. Süresi dolan anahtarlar belirgin bir auth hatası ile başarısız olmalı ki geliştiriciler neyi düzeltmeleri gerektiğini bilsin.\n\n## Kotalar ve Rate Limiting: Kullanımı Nasıl Uygularsınız\n\nRate limitler ve kotalar farklı sorunları çözer; karıştırılması “neden engellendim?” gibi kafa karıştırıcı destek taleplerinin yaygın nedenidir.\n\n### Rate limit vs kota\n\nRate limitler ani patlamaları kontrol eder (örn. “saniyede 50'den fazla istek yok”). Altyapınızı korur ve gürültülü bir müşterinin herkesi etkilemesini önler.\n\nKotalar bir dönemdeki toplam tüketimi sınırlar (örn. “ayda 100.000 istek”). Plan uygulama ve faturalama sınırlarıyla ilgilidir.\n\nBirçok ürün ikisini de kullanır: fairness ve fiyatlandırma için aylık kota ve stabilite için saniye/dakika rate limit.\n\n### Uygulama algoritmasını seçin\n\nGerçek zamanlı rate limiting için açıklanabilir ve güvenilir bir algoritma seçin:\n\n- Token bucket: tokenler zamanla dolar; her istek bir token harcar. Küçük patlamalara izin verirken ortalama hızı korur.\n- Leaky bucket: istekler sabit bir hızda “damlar”. Trafiği düzleştirir ama daha katı hissedilebilir.\n\nToken bucket genellikle geliştirici odaklı API'ler için varsayılan olarak daha uygundur çünkü öngörülebilir ve affedicidir.\n\n### Sayaçlar nerede tutulur seçin\n\nGenellikle iki depoya ihtiyacınız var:\n\n- Gerçek zamanlı, atomik kontroller için Redis (veya benzeri) gateway/edge'de.\n- Dayanıklı raporlama ve faturalama geçmişi için veritabanınız.\n\nRedis “bu istek şimdi çalışabilir mi?” sorusunu yanıtlar. Veritabanı “bu ay ne kadar kullandılar?” sorusunu yanıtlar.\n\n### Neyi kullanım sayacına dahil edeceğinizi tanımlayın\n\nÜrününüze ve endpointlerinize göre açık olun. Yaygın sayaçlar: istekler, tokenler, aktarılmış bayt, endpoint ağırlıkları veya hesaplama süresi.\n\nAğırlıklı endpoint kullanıyorsanız, ağırlıkları dokümantasyonda ve portalda yayınlayın.\n\n### Hata yanıtlarını eyleme geçirilebilir yapın\n\nİsteği engellediğinizde açık, tutarlı hatalar döndürün:\n\n- Rate limiting için 429 Too Many Requests. Retry-After ve isteğe bağlı X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset başlıklarını ekleyin.\n- Üst kota için ücretli planlarda 402 Payment Required (veya 403). Mevcut dönem kullanımını, kota limitini ve /billing veya /pricing gibi sonraki adımı gösterin.\n\nİyi mesajlar churn'u azaltır: geliştiriciler geri çekilme, yeniden deneme veya yükseltme yapmayı bilirler.\n\n## Kullanım Ölçümü: Olayları Toplama ve Agregasyon\n\nKullanım ölçümü kotalar, faturalar ve müşteri güveni için “gerçek kaynak”tır. Hedef basit: ne olduğunu tutarlı şekilde saymak, API'nizi yavaşlatmadan.\n\n### Her istek için ne loglamalısınız (ne değil)\n\nHer istek için küçük, öngörülebilir bir olay yükü yakalayın:\n\n- timestamp (sunucu zamanı)\n- key_id (veya token identifier)\n- endpoint (route adı, tam URL değil)\n- status (örn. 200, 401, 429)\n- units (sayılacak miktar: 1 istek, tokenler, bayt vb.)\n\nİstek/cevap gövdelerini loglamaktan kaçının. Yetki başlıklarını varsayılan olarak redakte edin (Authorization, cookies) ve KŞV/PII'yi sadece güçlü bir gerekçe ile “isteğe bağlı” yapın. Hata ayıklama için bir şey loglamanız gerekirse, ayrı daha kısa saklama süreli ve sıkı erişim kontrolleri olan bir yerde tutun.\n\n### API'yi hızlı tutmak için bir olay pipeline'ı kullanın\n\nMetrikleri istek sırasında toplamayın. Bunun yerine:\n\n1. API olayı bir kuyruğa/stream'e (veya hafif append-only tabloya) yazar.\n2. Bir worker olayları tüketir ve günlük/saatlik agregasyonları günceller.\n\nBu, trafik patladığında gecikmeyi sabit tutar.\n\n### Idempotency, yeniden denemeler ve çift sayımı önleme\n\nKuyruklar mesajları birden çok kez teslim edebilir. Benzersiz bir event_id ekleyin ve deduplikasyon uygulayın (benzersiz kısıtlama veya TTL ile “görülen” cache). Worker'lar yeniden denemeye karşı güvenli olmalı ki bir çökme toplamları bozmasın.\n\n### Saklama: ham kısa dönem, agregatlar uzun dönem\n\nHam olayları incelemeler için kısa süre saklayın (günler/haftalar). Agregre metrikleri trendler, kota uygulama ve faturalama hazırlığı için çok daha uzun tutun (aylar/yıllar).\n\n## İnsanların Gerçekten Kullandığı Analitik Panoları\n\nBir kullanım panosu sadece “güzel grafik” sayfası olmamalı. Hızlıca iki soruyu yanıtlamalı: ne değişti? ve sonraki adım ne olmalı? Tasarım kararlar etrafında olsun—spike'ları debug etmek, aşımı önlemek ve müşteriye değer kanıtlamak.\n\n### İlk göndereceğiniz temel görünümler\n\nGünlük ihtiyaçlara cevap veren dört panelle başlayın:\n\n- Zamana göre kullanım (istek/gün veya istek/dak), önceki dönemle karşılaştırma.