API Anahtarlarını, Kotaları ve Kullanım Analitiğini Yöneten Bir Web Uygulaması İnşa Edin
API anahtarları veren, kotaları uygulayan, kullanımı izleyen ve net analitik panolar sunan bir web uygulaması nasıl tasarlanır ve inşa edilir öğrenin.
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.
SSS
What’s the minimum viable feature set for an API key management portal?
Focus on three outcomes:
Issue and revoke keys safely (show the secret once, support expiry).
Enforce basic limits (rate limits + a simple daily/monthly quota).
Explain usage and blocks (a small dashboard + clear 429/over-quota messages).
If users can create a key, understand their limits, and verify usage without filing a ticket, your MVP is doing its job.
Should I enforce API keys and limits at a gateway, reverse proxy, or in application middleware?
Pick based on where you want consistent enforcement:
API gateway: best for multiple services and centralized policy; can be harder to debug without strong tracing.
Reverse proxy: lightweight edge enforcement, but complex plan rules may push you toward extra services.
App middleware: fastest MVP (one codebase), but watch for duplicated logic as you add services.
A common path is middleware first, then extract to a shared edge layer when the system grows.
How should I store API keys securely in my database?
Store metadata separately from the secret:
Save a prefix (first 6–8 chars) for display/search.
Save a for verification (never the raw token).
What’s the difference between rate limits and quotas, and do I need both?
They solve different problems:
Rate limits cap bursts (e.g., 60 req/min) to protect reliability.
Quotas cap total usage over a window (e.g., 100k/month) for plan enforcement and billing boundaries.
Many APIs use both: a monthly quota plus a per-second/per-minute rate limit to keep traffic stable.
How do I meter API usage without slowing down my API?
Use a pipeline that keeps the request path fast:
On each request, emit a small usage event (timestamp, key id, endpoint, status, units).
Write it to a queue/stream (or append-only log).
A worker aggregates into hourly/daily/monthly totals.
This avoids slow “counting” in-line while still producing billing-grade rollups.
How do I prevent double-counting in a usage event pipeline?
Assume events can be delivered more than once and design for retries:
Add a unique event_id per request.
Deduplicate in the consumer (unique constraint, or a “seen IDs” cache with TTL).
Make aggregation updates idempotent so a worker crash doesn’t corrupt totals.
This is essential if you’ll later use usage for quotas, invoices, or credits.
What should I include in audit logs for a key and quota management system?
Auth/admin activity: logins, role changes, suspicious spikes.
Include actor, target, timestamp, and IP/user-agent. When support asks “who revoked this key?”, you’ll have a definitive answer.
How should I design roles and permissions for a multi-tenant API portal?
Use a small, explicit role model and fine-grained permissions:
Roles like Owner, Admin, Developer, Read-only, Finance.
Permissions like and so you can add features without redefining roles.
How long should I retain raw usage events vs aggregated metrics?
A practical approach is raw short-term, aggregates long-term:
Keep raw events for days/weeks for investigations.
Keep rollups (daily/monthly totals) for months/years for trends and billing readiness.
Decide this up front so storage costs, privacy posture, and reporting expectations stay predictable.
What should my API return when a request is blocked, and how do I make it actionable?
Make blocks easy to debug without guesswork:
For rate limiting, return 429 with Retry-After and (optionally) X-RateLimit-* headers.
API Anahtarlarını, Kotaları ve Kullanım Analitiğini Yöneten Bir Web Uygulaması İnşa Edin | Koder.ai
En çok kullanılan endpointler (hacim ve maliyet/ağırlığa göre).
Hata oranı (4xx vs 5xx) böylece istemci hatalarını servis hatalarından ayırabilirsiniz.
Gecikme (isteğe bağlı) p50/p95; güvenilir ölçebiliyorsanız ekleyin.
\n### Eyleme geçirilebilir yapın, süs olsun diye değil\n\nHer grafik bir sonraki adımla bağlantılı olmalı. Gösterin:\n\n- Bu dönem kalan kota (örn. 18.200 / 50.000 kaldı)
Mevcut hızla projeksiyon: “aşılacak / altında kalacak” gibi basit bir işaret
\nProjeksiyon aşım olasılığı gösteriyorsa doğrudan yükseltme yoluna link verin: /plans (veya /pricing).\n\n### İnsanların çalışma biçimine uyan filtreleme\n\nKarmaşık sorgu oluşturucular zorlamadan incelemeyi daraltan filtreler ekleyin:\n\n- Zaman aralığı (son 24s, 7g, 30g, özel)
API anahtarı, proje, environment (prod/staging)
Endpoint ve status kod ailesi\n\n### Dışa aktarma ve API erişimi\n\nFinans ve destek için CSV indir ve müşterilerin kullanımı kendi BI araçlarına çekmesi için basit bir metrik API'si sağlayın (örn. GET /api/metrics/usage?from=...&to=...&key_id=...).\n\n## Uyarılar, Bildirimler ve Faturalama Hazırlığı\n\nUyarılar “biz fark ettik” ile “müşteriler önce fark etti” arasındaki farktır. Bunları kullanıcıların baskı altındaki sorularına göre tasarlayın: Ne oldu? Kim etkilendi? Bir sonraki adım ne olmalı?\n\n### Neye uyarı verilmeli (ve ne zaman)\n\nKotalara bağlı tahmin edilebilir eşiklerle başlayın. İyi bir desen %50 / %80 / %100 kota kullanımı içinde bildirim göndermektir.\n\nBirkaç yüksek sinyal davranış uyarısı ekleyin:\n\n- Olağandışı spike'lar: kiracının son ortalamasından keskin sapma (örn. saatlik ortalamanın 3×'ü)
Kimlik doğrulama hataları: geçersiz anahtar kullanımı veya imza hatalarında ani artış
Rate-limit baskısı: sürdürülen throttling olayları yanlış yapılandırılmış bir istemciyi gösterir\n\nUyarıları eyleme geçirilebilir yapın: kiracı, API anahtarı/uygulama, endpoint grubu, zaman aralığı ve portaldaki ilgili görünüme bir bağlantı (örn. /dashboard/usage) ekleyin.\n\n### Bildirim kanalları\n\nE-posta temel düzeydir çünkü herkesde vardır. Webhook ekleyin ki ekipler uyarıları kendi sistemlerine yönlendirsin. Slack destekliyorsanız isteğe bağlı tutun ve kurulum hafif olsun.\n\nPratik bir kural: kiracı başına bildirim politikası sunun—kim hangi uyarıları alır ve hangi şiddette.\n\n### İnsanların okuduğu basit kullanım raporları\n\nGünlük/haftalık bir özet sunun: toplam istekler, en çok kullanılan endpointler, hatalar, throttling ve “önceki döneme göre değişim”. Paydaşlar ham log değil trend görmek ister.\n\n### Faturalamaya hazırlık ama faturalamaya bağlı kalma\n\nFaturalama “sonra” olsa bile şunları saklayın:\n\n- Plan geçmişi (kiracı hangi plandaydı ve ne zaman)
Fiyatlandırma yürürlük tarihleri (yeniden hesaplamalar tutarlı olsun diye)
\nBu, fatura veya önizleme backfill etmenize veri modelini yeniden yazmadan izin verir.\n\n### Açık mesaj şablonu\n\nHer ileti: ne oldu, etki, ve sonraki adım (anahtarı döndür, planı yükselt, istemciyi incele veya /support ile iletişime geç) belirtmeli.\n\n## Güvenlik ve Uyumluluk Temelleri\n\nAPI anahtar yönetim uygulaması için güvenlik süslü özelliklerden çok dikkatli varsayılanlar ile ilgilidir. Her anahtarı bir kimlik bilgisi gibi ele alın ve yanlış yere kopyalanacağı varsayımıyla tasarım yapın.\n\n### API anahtarlarını koruma\n\nAnahtarları asla düz metin saklamayın. Sırdan türetilmiş bir verifier saklayın (genellikle SHA-256 veya HMAC-SHA-256 sunucu tarafı pepper ile) ve kullanıcıya tam sırrı yalnızca oluşturma sırasında gösterin.\n\nUI ve loglarda sadece güvenli olmayan olmayan bir önek gösterin (ör. ak_live_9F3K…) ki insanlar anahtarı tanıyabilsin ama açıkça maruz kalmasın.\n\nKullanıcılara anahtarları Git'e commit etmemeleri konusunda pratik “secret scanning” rehberliği sağlayın ve portal dokümanlarında ilgili araçlardan (ör. GitHub secret scanning) bahsedin /docs sayfasında.\n\n### Genellikle gözden kaçan yönetici korumaları\n\nSaldırganlar yönetici uç noktalarını sever çünkü anahtar oluşturabilir, kotaları yükseltebilir veya limitleri devre dışı bırakabilirler. Yönetici API'larına da rate limiting uygulayın ve yönetici erişimi için IP allowlist seçeneğini düşünün (iç ekipler için faydalı).\n\nEn az ayrıcalık ilkesini uygulayın: viewer vs admin ayrımı, kimin kotaları değiştirebileceğini veya anahtar döndürebileceğini sınırlayın.\n\n### Denetim kayıtları ve saklama\n\nAnahtar oluşturma, döndürme, iptal, giriş denemeleri ve kota değişiklikleri için denetim olayları kaydedin. Logları değiştirilemez hale getirin (append-only, sınırlı yazma erişimi ve düzenli yedekleme).\n\nUyumluluk temellerini erken benimseyin: veri minimizasyonu (sadece gerekeni saklayın), açık saklama kontrolleri (eski logları otomatik silme) ve belgelenmiş erişim kuralları.\n\n### Tehdit senaryoları için tasarım\n\nAnahtar sızıntısı, replay suistimali, portalınızın taranması ve paylaşılan kapasiteyi tüketen “gürültülü komşu” kiracıları. Bu risklere karşı mitigasyonları (hashing/verifier'lar, mümkünse kısa ömürlü tokenler, rate limitler ve kiracı başına kotalar) uygulayın.\n\n## Yönetici ve Geliştirici Portalı UX\n\nHarika bir portal “güvenli yolu” en kolay yol yapar: yöneticiler riski hızlıca azaltabilir, geliştiriciler çalışır bir anahtar alır ve test çağrısı yapabilirler kimseye e-posta atmaya gerek kalmadan.\n\n### Yönetici UX: hız, kontrol ve güven\n\nYöneticiler genelde acil bir görevle gelir (“bu anahtarı şimdi iptal et”, “bunu kim oluşturdu?”, “kullanım neden arttı?”). Hızlı tarama ve kesin hareket için tasarlayın.\n\nAnahtar öneki, uygulama adları, kullanıcılar ve workspace/tenant adları arasında çalışan hızlı arama sağlayın. Bunu net durum göstergeleri (Active, Expired, Revoked, Compromised, Rotating) ve “son kullanıldı” ile “oluşturuldu” gibi zaman damgalarıyla eşleştirin. Bu iki alan yanlış iptalleri önler.\n\nYüksek hacimli işlemler için bulk action ekleyin: toplu iptal, toplu döndürme, toplu kota değişikliği. Her zaman bir onay adımı ve etki özeti gösterin (“38 anahtar iptal edilecek; 12'si son 24 saatte kullanıldı”).\n\nHer anahtar için denetim-dostu detay paneli sağlayın: scope'lar, ilişkili uygulama, izin verilen IP'ler (varsa), kota seviyesi ve son hatalar.\n\n### Geliştirici UX: başarıyı anında sağlayın\n\nGeliştiriciler kopyala-yapıştır yapıp devam etmek ister. Anahtar oluşturma akışının yanında net dokümanlar koyun, gömülü değil. Kopyalanabilir curl örnekleri ve mümkünse dil seçici (curl, JS, Python) sunun.\n\nAnahtarı bir kez gösterin, “kopyala” butonu ve kısa bir hatırlatıcı verin. Ardından bir “Test call” adımıyla sandbox veya düşük riskli bir endpoint'e gerçek bir istek çalıştırma rehberi sağlayın. Başarısız olursa, düz İngilizce (veya hedef dilde) hata açıklamaları verin ve yaygın çözümleri gösterin:\n\n- “Invalid key” → header adı ve boşlukları kontrol edin\n- “Forbidden” → eksik scope/izin\n- “Rate limited” → kotaları ve retry-after başlığını nasıl göreceğinizi açıklayın\n\n### Kendin yap onboarding birkaç dakikada\n\nBasit bir yol en iyisidir: İlk anahtarı oluştur → test çağrısı yap → kullanımı gör. Küçük bir kullanım grafiği bile (“Son 15 dakika”) metering'in çalıştığına dair güven yaratır.\n\nİlgili sayfalara göreceli yollarla bağlantı verin: /docs, /keys, ve /usage.\n\n### Erişilebilirlik ve açıklık\n\nAçık etiketler kullanın (“Requests per minute”, “Monthly requests”) ve birimler sayfalar arasında tutarlı olsun. “Scope” ve “burst” gibi terimler için tooltip ekleyin. Klavye navigasyonu, görünür odak durumları ve yeterli kontrast sağlayın—özellikle durum rozetleri ve hata bantlarında.\n\n## Dağıtım, İzleme ve Test\n\nBu tür bir sistemi üretime almak büyük ölçüde disiplinle ilgilidir: öngörülebilir deploy'lar, bir şey bozulduğunda net görünürlük ve “sıcak yollar” (auth, rate kontrolleri, ölçüm) üzerine odaklı testler.\n\n### Dağıtım ayarları (secret'lar, env var'lar, migrationlar)\n\nKonfigürasyonu açık tutun. Duyarsız ayarları environment değişkenlerinde tutun (örn. rate-limit varsayılanları, kuyruk isimleri, saklama pencereleri) ve sırları yönetilen bir secret store'da (AWS Secrets Manager, GCP Secret Manager, Vault) saklayın. Key'leri imajlara gömmeyin.\n\nVeritabanı migrationlarını pipeline'ınızda birinci sınıf adım olarak çalıştırın. Geriye uyumlu değişiklikler için “migrate then deploy” stratejisi tercih edin ve güvenli rollback planlayın (özellikle feature flag'ler yardımcı olur). Çok kiracılıysanız, her kiracıyı tarayan bir migration yapmaktan kaçınmak için kontrol mekanizmaları ekleyin.\n\nEğer sistemi Koder.ai üzerine kuruyorsanız, snapshot ve rollback erken iterasyonlarda (özellikle uygulama mantığı ve şema sınırlarını incelerken) pratik bir güvenlik ağı sağlar.\n\n### Gözlemlenebilirlik gerçek soruları yanıtlamalı\n\nÜç sinyale ihtiyacınız var: loglar, metrikler ve trace'ler. Rate limiting ve kota enforcement'ı şu metriklerle instrument edin:\n\n- İzin verilen vs reddedilen istekler (API anahtarı, endpoint ve kiracı bazında)
Red neden kodları (rate limit, kota aşıldı, geçersiz anahtar)
Metering pipeline gecikmesi (olay ingest → agregasyon gecikmesi)
\nDestek ekibinin “trafiğim neden başarısız oluyor?” sorusuna cevap verebilmesi için rate-limit reddetmelerine özel bir pano oluşturun. Tracing, kritik yol üzerindeki (anahtar durumu DB sorguları, cache missleri vb.) yavaş bağımlılıkları tespit etmeye yardımcı olur.\n\n### Yedekleme ve kurtarma öncelikleri\n\nKonfigürasyon verilerini (anahtarlar, kotalar, roller) yüksek öncelikli; kullanım olaylarını yüksek hacimli olarak ele alın. Konfigürasyonu sık sık yedekleyin ve point-in-time recovery sağlayın.\n\nKullanım verileri için dayanıklılık ve replay önemlidir: write-ahead log/queue ve yeniden-aggregate etmek sık yedek almaktan daha pratik olabilir.\n\n### Test ve rollout planı\n\nLimit mantığını birim testleriyle (kenar durumlar: pencere sınırları, eşzamanlı istekler, anahtar döndürme) doğrulayın. En sıcak yolları yük testine tabi tutun: anahtar doğrulama + sayaç güncellemeleri.\n\nArdından kademeli rollout yapın: dahili kullanıcılar → sınırlı beta (seçili kiracılar) → genel erişim; enforcement'ı devre dışı bırakabilecek bir kill switch bulundurun.
hash
Track lifecycle fields like created_at, last_used_at, expires_at, and status.
In the UI, show the full key only once at creation and make it clear it can’t be recovered later.
keys:rotate
quotas:update
Enforce tenant isolation everywhere (e.g., org_id on every query), not just via UI filters.
For over-quota, return 402 (or 403) and include the current period usage, limit, and a link to the next step (e.g., /plans or /billing).
Pair this with portal pages that answer “why was I blocked?” and let users verify usage in /usage (and deeper details in /blog/usage-metering if you have it).