API Bazlı Kota

ipucu

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

Genel Bakış

API Tabanlı Kota politikası, API kullanımını belirli zaman periyotları (saat, gün, ay) boyunca sınırlandıran bir kaynak yönetim mekanizmasıdır.

Amacı Nedir?

• Kullanım Kotası Yönetimi: API kullanımını saatlik, günlük veya aylık periyotlarda sınırlandırarak kaynak tüketimini kontrol eder ve adil kullanım sağlar.
• İş Modeli ve Fiyatlandırma Desteği: Farklı müşteri segmentleri için özelleştirilmiş kota planları sunar (Free: 1000 istek/ay, Basic: 10K/ay, Premium: 100K/ay, Enterprise: Unlimited), abonelik modellerini destekler.
• Maliyet Kontrolü ve Bütçe Yönetimi: Cloud servis maliyetlerini tahmin edilebilir kılar, müşteri başına kaynak tüketimini izler, beklenmedik maliyet artışlarını önler.
• SLA ve Servis Kalitesi Garantisi: Servis seviyesi sözleşmelerini yerine getirir, tüm kullanıcıların API kaynaklarına erişimini garanti eder, kaynak tükenmesini önler.
• Abuse ve Kötüye Kullanım Önleme: Aşırı kullanımı tespit eder ve engeller, API kaynaklarının adil dağılımını sağlar, hizmet kesintilerini önler.

Çalışma Prensibi

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak bilgileri (IP, kullanıcı, API key vb.) ve zaman damgası tespit edilir.
2. Politika Kontrolü: API Tabanlı Kota politikası aktif ise, sistem aşağıdaki sırayla kontrol yapar:

• Condition (koşul) tanımlı mı? Varsa koşul sağlanıyor mu?
• Politika aktif mi (active=true)?
• Variable kullanılıyor mu yoksa Apinizer default mı?

3. Quota Key Oluşturma ve Sayaç Kontrolü: Her istek için benzersiz bir kota anahtarı oluşturulur (format: quota:{policy_id}:{apply_by_value}:{period}). Apply By parametresi varsa (IP adresi, kullanıcı ID, API key), bu değer anahtara dahil edilir. Redis cache'den mevcut kota kullanım sayacı sorgulanır. Detail List tanımlıysa, hedef değer ile karşılaştırılır ve eşleşen kuralın kotası kullanılır, yoksa varsayılan kota uygulanır.
4. Karar Verme:

• Kota Aşılmadıysa:
  • Sayaç 1 artırılır ve cache'e senkron olarak yazılır
  • İstek backend'e iletilir
  • Kota bilgisi veritabanına asenkron olarak güncellenir (API yanıt süresini etkilemez)
  • Rate limit statistics aktifse response header'larına kalan kota bilgisi eklenir (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
• Kota Aşıldıysa:
  • HTTP 429 (Too Many Requests) hatası dönülür, istek işlenmez
  • Kota yenileme zamanı response header'ında belirtilir
  • Cache hatası durumunda Cache Bağlantı Hatası Eylemi devreye girer (Fail: istek hata ile reddedilir, Continue: istek reddedilmeden akış devam eder)

5. Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.

Veri Depolama Mimarisi

API Tabanlı Kota politikası, veri tutarlılığı ve kalıcılığı sağlamak için iki katmanlı bir depolama stratejisi kullanır:

Cache (Redis) - Birincil Katman:

• Gerçek zamanlı kota kontrolleri için kullanılır
• Her API isteğinde senkron olarak güncellenir
• Yüksek performans ve düşük gecikme sağlar
• Dağıtık sistemlerde tüm Gateway instance'ları aynı sayaçları paylaşır

Veritabanı - İkincil Katman:

• Uzun vadeli kota verilerinin kalıcı saklanması için kullanılır
• API yanıt süresini etkilememek için asenkron olarak güncellenir
• Sistem yeniden başlatıldığında veya cache hatası durumunda veri kaybını önler
• Raporlama, analitik ve faturalama için güvenilir veri kaynağı sağlar
• Kota geçmişi ve kullanım istatistikleri için arşiv tutar

Senkronizasyon Stratejisi: Başarılı her istek sonrasında kota bilgileri iki aşamada güncellenir:

1. Öncelikle Redis cache hızlıca güncellenir (senkron) - API yanıt süresine dahil
2. Ardından veritabanı güncellemesi asenkron olarak gerçekleştirilir - API yanıt süresini etkilemez

Bu yaklaşım, yüksek performans ve veri dayanıklılığı arasında optimal bir denge kurar.

Özellikler ve Yetenekler

Temel Özellikler

• Kota Sayısı Limiti: Belirli bir zaman periyodunda izin verilen maksimum toplam istek sayısını belirler (minimum 1, tam sayı).
• Uzun Dönem Zaman Aralığı Desteği: Saat, Gün ve Ay bazında kota periyotları tanımlama. Periyot uzunluğu çarpanı ile özelleştirilebilir zaman aralıkları (örn: 7 gün, 3 ay).
• Apply By Değişkeni: Kota'nın hangi kritere göre uygulanacağını belirler (kullanıcı ID bazlı, API Key bazlı, müşteri ID bazlı, abonelik tipi bazlı). Her değişken değeri için ayrı kota sayacı tutulur.
• Aktif/Pasif Durum Kontrolü: Politikanın aktif veya pasif durumunu kolayca değiştirme (active/passive toggle). Pasif durumda politika uygulanmaz ancak yapılandırması saklanır.
• Koşul Bazlı Uygulama: Query Builder ile karmaşık koşullar oluşturarak politikanın ne zaman uygulanacağını belirleme (örn: sadece belirli endpoint'lere veya kullanıcı tiplerine göre).

İleri Düzey Özellikler

• Hedef Bazlı Farklı Kotalar (Detail List): Belirli hedef değerler (kullanıcı seviyeleri, abonelik planları, müşteri segmentleri) için özel kota kuralları tanımlama. Regex desteği ile esnek hedef eşleşmeleri. Her hedef için ayrı kota sayısı ve zaman periyodu.
• Interval Window Type Desteği: SLIDING (Kayan Pencere) - Her istek zamanından geriye doğru pencere uygulanır, son N gün/saat içindeki kullanım. FIXED (Sabit Pencere) - Belirli zaman dilimlerinde sayaç sıfırlanır (örn. her ayın 1'i), daha yaygın kullanım.
• Sayım Modu: Kota zaten aşıldığı için reddedilen isteklerin de kotayı tüketip tüketmeyeceğini belirler. Varsayılan (Tüm istekler) modda kabul edilen veya reddedilen her istek kullanım sayacını artırır — Apinizer'ın tarihsel davranışıyla aynıdır. Yalnızca kabul edilenler seçilirse reddedilen bir istek kotayı hiç tüketmez.
• Limit Değişimi Davranışı: Politika kullanımdayken Kota Sayısı değeri değiştirildiğinde mevcut kullanım sayacına ne olacağını belirler. Varsayılan (Dokunma) modda sayaç olduğu gibi bırakılır ve yeni limit bir sonraki istekten itibaren bu sayaçla karşılaştırılır. Sayacın önceki limit değerine kırpılması ya da yalnız limit yükseltildiğinde (limit düşürüldüğünde asla) sıfırlanması da seçilebilir.
• Cache Bağlantı ve Hata Yönetimi: Cache sunucusu bağlantı timeout süresi ayarlama (saniye). Cache erişilemezse davranış belirleme: Fail (varsayılan, istek reddedilir) veya Continue (istek reddedilmez).
• Rate Limit İstatistikleri: Response header'larında kalan kota bilgisi gösterme (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Client'ların ve dashboard'ların kota durumunu takip edebilmesi.
• Dağıtık Mimari Desteği: Merkezi Redis cache kullanımı sayesinde birden fazla Gateway instance'ı aynı kota sayaçlarını paylaşır. Kullanıcı hangi gateway'e bağlanırsa bağlansın tutarlı kota takibi garantisi.
• Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) import etme. Versiyon kontrolü ve yedekleme imkanı.
• Policy Group ve Proxy Group Desteği: Birden fazla politikayı Policy Group içinde yönetme. Proxy Group'lara toplu politika atama. Merkezi güncelleme ve deploy işlemleri.
• Deploy ve Versiyonlama: Politika değişikliklerini canlı ortama deploy etme. Hangi API Proxy'lerde kullanıldığını görme (Policy Usage). Proxy Group ve Policy Group kullanım raporları.

Kullanım Senaryoları

API Based Quota politikası, API kullanımını uzun dönemli periyotlarda (saatlik, günlük, aylık) sınırlamak ve kontrol altında tutmak amacıyla toplam istek sayısını yönetir. Aşağıdaki örnek senaryolar, farklı kullanım durumlarında bu politikanın nasıl uygulanabileceğini göstermektedir.

Senaryo	Durum	Çözüm (Politika Uygulaması)	Beklenen Davranış / Sonuç
Aylık Abonelik Planları	Farklı abonelik seviyelerine göre aylık kota belirlemek istiyorsunuz	Apply By: {user.subscription_plan}, Kota: 1000/ay (varsayılan), Detail List: free=1000/ay, basic=10000/ay, premium=100000/ay, enterprise=1000000/ay	Her abonelik planına göre aylık kota uygulanır. Ay sonunda otomatik sıfırlanır. Free: 1K, Basic: 10K, Premium: 100K, Enterprise: 1M istek/ay
API Key Bazlı Günlük Kota	Her API key için günlük kullanım limiti koymak istiyorsunuz	Apply By: {request.header.X-API-Key}, Kota: 5000, Periyot: 1 Gün, Interval Window Type: FIXED	Her API key günde 5000 istek yapabilir. Her gün başında sayaç sıfırlanır. Müşteriler günlük kotalarını yönetebilir
Ücretsiz Deneme Dönemi	Ücretsiz kullanıcılara 7 günlük deneme kotası vermek istiyorsunuz	Kota: 500, Periyot: 7 Gün, Interval Window Type: FIXED, Koşul: {user.account_type} = trial	Deneme hesapları 7 gün boyunca toplam 500 istek yapabilir. Süre sonunda kota sıfırlanmaz, hesap yükseltilmesi gerekir
Kullanıcı Bazlı 7 Günlük Limit	Her kullanıcı için 7 günlük toplam kota tanımlamak istiyorsunuz	Apply By: {user.id}, Kota: 10000, Periyot: 7 Gün, Show Rate Limit Statistics: Aktif	Her kullanıcı 7 günlük periyotta 10000 istek yapabilir. Kullanıcılar kalan kotalarını görebilir
Premium Müşteriler İçin Özel Kota	Özel sözleşmeli müşterilere yüksek aylık kota vermek istiyorsunuz	Apply By: {customer.id}, Kota: 50000/ay, Detail List: customer_A=500000/ay, customer_B=1000000/ay, customer_C=2000000/ay	Standart müşteriler 50K/ay, özel sözleşmeli müşteriler anlaşmaya göre çok daha yüksek kotalar alır
Endpoint Bazlı Farklı Kotalar	Resource-intensive endpoint'ler için daha düşük kota uygulamak istiyorsunuz	Politika 1: Kota: 100/gün, Koşul: {request.path} = /api/export. Politika 2: Kota: 10000/gün, Koşul: diğerleri	Export endpoint'i günde 100 kez, normal endpoint'ler 10000 kez kullanılabilir. Kaynak yoğun işlemler sınırlandırılır
Sliding Window ile Esnek Kota	Son 30 gün içinde toplam kullanım limiti koymak istiyorsunuz	Kota: 100000, Periyot: 30 Gün, Interval Window Type: SLIDING	Her an son 30 gündeki toplam istek sayısı kontrol edilir. Daha esnek ve adil kota yönetimi sağlanır

Politika Parametrelerini Yapılandırma

Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir.

Yeni API Tabanlı Kota Politikası Oluşturma

Yapılandırma Adımları

Adım	Açıklama / İşlem
Adım 1: Oluşturma Sayfasına Gitme	- Sol menüden Development → Global Settings → Global Policies → API Based Quota bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın.
Adım 2: Temel Bilgileri Girme	Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: Monthly_Premium_User_Quota - Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: "Premium kullanıcılar için aylık 100.000 istek kotası" - Maks. 1000 karakter. - Politikanın amacını açıklayın.
Adım 3: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: Kota Ayarlarını Yapılandırma	Rate Limit İstatistiklerini Response Header'da Göster: - Toggle switch ile aktif/pasif yapın. - Aktif olduğunda response header'larında X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset bilgileri gösterilir. Uygulama Değişkeni (Apply By): İsteğe Bağlı - "Değişken Seç" butonuna tıklayın. - Kota'nın hangi kritere göre uygulanacağını belirler. - Örnekler: {user.id} (kullanıcı bazlı), {user.subscription} (abonelik tipi bazlı), {request.header.X-API-Key} (API key bazlı) - Değişken seçilmezse tüm istekler aynı kotayı paylaşır. Kota Sayısı: Zorunlu, Minimum: 1 - İzin verilen maksimum toplam istek sayısı. - Örnek: 100000 per (görsel metin) Periyot Uzunluğu: Zorunlu, Minimum: 1 - Zaman aralığının çarpanı. - Örnek: 1 Zaman Birimi: Zorunlu - Bir Saat, Bir Gün, Bir Ay - Örnek: Ay Örnek Yapılandırma: 100000 istek / 1 Ay → Ayda maksimum 100000 istek
Adım 5: Hedef Bazlı Kurallar Tanımlama (İsteğe Bağlı)	Detail List (Hedef Bazlı Kota Kuralları): - Farklı hedef değerler için özel kotalar tanımlayın. - "+" butonuna tıklayarak yeni satır ekleyin. Tablo Kolonları: - Hedef Değer: Değişken değeri (örn: "premium", "enterprise", "trial") - Zorunlu - Regex İfade: Hedef değerin regex olup olmadığı - Toggle (Boolean) - Kota Sayısı: Bu hedef için toplam istek limiti - Number (Min: 1) - Periyot Uzunluğu: Zaman aralığı çarpanı - Number (Min: 1) - Zaman Birimi: Saat/Gün/Ay - Dropdown Kullanım Senaryoları: - Free kullanıcılar: free → 1000 istek/ay - Basic kullanıcılar: basic → 10000 istek/ay - Premium kullanıcılar: premium → 100000 istek/ay - Enterprise müşteriler: enterprise → 1000000 istek/ay Silme: Satır sonundaki çöp kutusu ikonu ile satırı kaldırın.
Adım 6: Gelişmiş Ayarları Yapılandırma	Interval Window Type: Zorunlu - SLIDING (Kayan Pencere): Her istek zamanından geriye doğru pencere uygulanır. Örnek: Son 30 gündeki toplam istek sayısı. Daha esnek ancak hesaplama maliyeti yüksek. - FIXED (Sabit Pencere): Belirli zaman dilimlerinde sıfırlanır. Örnek: Her ayın 1'inde sayaç sıfırlanır. Daha yaygın ve performanslı. Faturalama döngüleriyle uyumlu. Cache Bağlantı Timeout: Zorunlu, Minimum: 0 saniye, arayüzde varsayılan: 10 saniye - Cache sunucusuna bağlantı timeout süresi. - Timeout durumunda hata yönetimi politikası devreye girer. - Önerilen: 1-3 saniye Cache Bağlantı Hatası Eylemi: Zorunlu, varsayılan: Fail - Fail: İstek hata ile reddedilir. - Continue: İstek reddedilmez, akış devam eder. Sayım Modu: Zorunlu, varsayılan: Tüm istekler - Tüm istekler: Kabul edilen veya reddedilen her istek kullanım sayacını artırır. - Yalnızca kabul edilenler: Sadece kotayı geçen istekler kullanım sayacını artırır; reddedilen istekler sayaca dokunmaz. Limit Değişimi Davranışı: Zorunlu, varsayılan: Dokunma - Önceki limite kırp: Kota Sayısı değeri değiştirildiğinde kullanım sayacı önceki limit değerine kırpılır (yeni değere değil). - Sıfırla: Kullanım sayacı sıfırlanır, ancak sadece limit yükseltildiğinde — limit düşürüldüğünde sayaç asla sıfırlanmaz. - Dokunma: Limit değiştiğinde kullanım sayacı olduğu gibi bırakılır. ⚠️ Önemli Notlar: Zaman Dilimi Ayarları: FIXED window kullanırken sistem saat dilimi ayarlarının doğru yapılandırıldığından emin olun. Özellikle gün/ay bazlı periyotlarda, zaman dilimi farklılıkları beklenmedik sıfırlama zamanlarına neden olabilir. Sıfırlama zamanları her zaman sunucu saat dilimine göre hesaplanır. Sabit Pencere Hesaplama (FIXED): - Bir günden kısa aralıklar için (örn: 6 saat): - Formül: Pencere Başlangıcı = Gün Başlangıcı + (Geçen Periyotlar × Periyot Süresi) - Örnek: Saat 14:37'deki bir istek, 6 saatlik periyotta → 12:00-17:59 penceresine aittir - Bir gün veya daha uzun aralıklar için (örn: 7 gün, 1 ay): - Formül: Pencere Başlangıcı = Unix Epoch + (Geçen Periyotlar × Periyot Süresi) - Örnek: 1 aylık periyotta her ayın 1'inde sayaç sıfırlanır Faturalama Entegrasyonu: Abonelik bazlı sistemlerde FIXED window type kullanarak faturalama döngünüzü kota yenileme zamanıyla senkronize edebilirsiniz. Bu sayede müşteri faturalandırma tarihi ile kota yenileme tarihi aynı olur.
Adım 7: Koşul Tanımlama (İsteğe Bağlı)	- Condition sekmesine geçin. - Koşullar, politikanın hangi durumda aktif olacağını belirler. Örnekler: - Kullanıcı tipi bazlı: Header = X-User-Type, Operator = Equals, Value = paid - Abonelik bazlı: Header = X-Subscription, Starts With = premium- - Hesap durumu: Header = X-Account-Status, Equals = active Koşul tanımlamazsa politika her zaman aktif
Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı)	- Error Message Customization sekmesine gidin. - Kota aşıldığında dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 429, "message": "Quota Exceeded" } Özel: { "statusCode": 429, "errorCode": "MONTHLY_QUOTA_EXCEEDED", "message": "Aylık kotanız dolmuştur. Yenilenme tarihi: {reset_date}. Planınızı yükseltmek için: /upgrade" }
Adım 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir mesaj sayısı ve zaman aralığı tanımlı Sonuç: - Politika listeye eklenir. - API'lere bağlanabilir. - Global politikaysa otomatik uygulanır.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

Politikayı Silme

Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.

Politikayı Dışa/İçe Aktarma

Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına bakabilirsiniz.

Politikayı API'ye Bağlama

Bu politikanın API'lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API'ye Bağlama bölümüne bakabilirsiniz.

İleri Düzey Özellikler

Bu bölümde kullanıcı, API Based Quota politikasının gelişmiş yönetim kabiliyetlerini kullanarak daha esnek, dinamik ve kurumsal seviyede kontrol elde eder.

Özellik	Açıklama ve Adımlar
Dinamik Kota Yenileme	- FIXED window type ile belirli günlerde otomatik sıfırlama ayarlayın (örn: her ayın 1'i). - Faturalama döngünüzle senkronize edin. - Customer billing date'e göre özel yenileme tarihleri tanımlayın. - Bu sayede her müşterinin kotası kendi abonelik yenileme gününde sıfırlanır.
Kota Rollover Özelliği	- Cache'de kullanılmayan kota miktarını saklayın. - Bir sonraki periyotta bonus olarak ekleyin. - Maksimum rollover limiti tanımlayın (örn: maksimum 2 aylık biriktirme). - Kullanılmayan kotaları bir sonraki döneme aktararak müşteri memnuniyeti artırın.
Soft Limit ve Hard Limit	- İki farklı quota politikası oluşturun. - Soft Limit (örn: 80000/ay): Uyarı göster ama izin ver. - Hard Limit (örn: 100000/ay): İstek reddet. - Müşterilere kota yaklaştığında uyarı vererek ani kesintileri önleyin.
Cache-Database Senkronizasyonu	- Düzenli olarak cache ve database'deki kota değerlerini karşılaştıran monitoring kurun. - Tutarsızlık tespit edilirse alert gönderin ve otomatik düzeltme mekanizması tetikleyin. - Yüksek trafikli saatlerde asenkron yazma sıklığını artırın, düşük trafikte azaltın. - Bu sayede veri tutarlılığını garanti ederken sistem güvenilirliğini artırın.

İpuçları ve En İyi Uygulamalar

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Kota Değerleri Belirleme	Kötü: Keyfi sayılar belirlemek (örn: 12345 istek/ay) - analiz eksikliği İyi: Geçmiş kullanım verilerine göre kota belirlemek En İyi: Percentile analizi yapın (örn: %95 kullanıcı 5K/ay altında), yeterli buffer ekleyin (%20-30 fazla), farklı kullanıcı segmentleri için ayrı analiz yapın
Window Type Seçimi	Kötü: Her senaryo için SLIDING kullanmak - gereksiz hesaplama yükü İyi: Abonelik bazlı sistemlerde FIXED tercih etmek En İyi: FIXED window type ile faturalama döngüsünü senkronize edin, müşteri başlangıç tarihini baz alın, ay sonu/başı sıfırlamayı planlayın
Apply By Değişkeni Stratejisi	Kötü: Apply By kullanmamak - tüm müşteriler aynı kotayı paylaşır İyi: User ID ile kullanıcı bazlı kota En İyi: Hiyerarşik yapı: Organization → Team → User. Enterprise müşterilerde organization ID, bireysel kullanıcılarda user ID kullanın. Multi-tenancy destekleyin.
Detail List ile Segmentasyon	Kötü: Tek tip kota - esneklik yok İyi: Free/Premium ayrımı yapın En İyi: Çok katmanlı tier sistemi: Trial/Free/Starter/Professional/Business/Enterprise. Her segment için ayrı fiyatlandırma ve kota. Upsell yolu açık bırakın.
Rate Limit Header Kullanımı	Kötü: Header'ları göstermemek - müşteri kotasını bilmez İyi: Sadece authenticated isteklerde header göstermek En İyi: Tüm isteklerde header aktif, dashboard/analytics entegrasyonu sağlayın, kota %80 dolduğunda email/notification gönderin, upgrade linki sağlayın

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Fatura Doğruluğu	Cache Bağlantı Hatası Eylemi'nde Fail seçeneğini (varsayılan) kullanın. Ödeme yapan müşterilerde kotanın kesinlikle doğru sayılması kritiktir. Cache problemi yaşanırsa servis geçici kesintiye uğramalı, fazla kullanım izni verilmemelidir. Veritabanı asenkron güncellemesi sayesinde cache hatası durumunda bile kota verileri kaybolmaz. Düzenli olarak cache-database senkronizasyonunu kontrol edin.
Fraud ve Abuse Önleme	Anormal kullanım paternlerini tespit edin (örn: günde 1000 istek yapan kullanıcı aniden 100K istek atıyorsa). Ani quota patlamaları için alert kurun. Şüpheli hesapları otomatik suspend edin.
API Key Güvenliği	API Key bazlı quota kullanırken key rotation stratejisi uygulayın. Sızan key'lerin zararını sınırlandırmak için kota çok kritiktir. Her key için separate quota tracking yapın.
Tenant Isolation	Multi-tenant sistemlerde her tenant için tamamen izole quota sayacı tutun. Bir tenant'ın kullanımı diğerlerini etkilememeli. Cache key'lerde tenant_id mutlaka bulunmalı.
Monitoring ve Alerting	Kota aşımlarını sürekli izleyin. %80 dolulukta uyarı, %100'de alert gönderin. Revenue impact analizi yapın (kaç müşteri kota yüzünden upgrade yaptı?). Abuse pattern'lerini tespit edin.

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Cache Bağlantı Hatası Eylemi'nde Continue Kullanımı (Ödeme Yapan Müşterilerde)	Neden kaçınılmalı: Cache hatası olduğunda kota kontrolü devre dışı kalır, müşteriler sınırsız kullanım yapabilir, fatura kayıpları oluşur, abuse riski artar Alternatif: Ödeme yapan müşterilerde Fail kullanın, cache high availability sağlayın, Redis cluster kurun, failover mekanizması oluşturun
Çok Kısa Periyotlar (Örn: Saatlik Kota)	Neden kaçınılmalı: Kota çok sık sıfırlanır, müşteri deneyimi kötüleşir, faturalama karmaşıklaşır, abuse kolay hale gelir Alternatif: Minimum günlük, idealda aylık periyotlar kullanın, kısa süreli koruma için throttling politikası ekleyin, quota + throttling kombinasyonu yapın
Değişken Olmadan Detail List Kullanımı	Neden kaçınılmalı: Apply By olmadan hedef eşleştirmesi çalışmaz, tüm Detail List kuralları etkisiz kalır, farklı kotalar uygulanamaz Alternatif: Mutlaka Apply By değişkeni tanımlayın, değişken değeri ile hedef değeri eşleşecek şekilde planlayın
Çok Yüksek Quota Değerleri (Ücretsiz Planlarda)	Neden kaçınılmalı: Abuse riski çok yüksek, maliyet kontrolü olmaz, upgrade motivasyonu azalır, sunucu kaynakları tükenir Alternatif: Ücretsiz planlar için makul limitler koyun (örn: 1000-5000/ay), upgrade path'i net gösterin, paid planların avantajlarını vurgulayın

Performans İpuçları

Kriter	Öneri / Etki
Cache Stratejisi	Öneri: Redis cluster kullanın, connection pooling aktif edin, read replica'lar ekleyin, cache key'leri optimize edin (kısa ve unique) Etki: Yüksek trafikte bile düşük latency, yüksek availability, tutarlı kota takibi
Cache Bağlantı Pooling	Öneri: Redis connection pool kullanın, connection pool size'ı trafiğinize göre optimize edin (önerilen: CPU core sayısı × 2), keepalive sürelerini ayarlayın, connection timeout'ları belirleyin Etki: Her istek için yeni connection açılmaz, bağlantı maliyeti %80 azalır, latency %30-50 düşer, cache sunucusu aynı anda daha fazla client'a hizmet verebilir
FIXED Window Tercihi	Öneri: Özellikle aylık quota'larda FIXED window kullanın, SLIDING yerine daha performanslı, faturalama döngüsüne uygun Etki: Cache okuması azalır, işlem maliyeti düşer, faturalama daha basit, müşteri deneyimi daha net
Detail List Optimizasyonu	Öneri: Detail List'i maksimum 20-30 kuralla sınırlayın, en sık kullanılan kuralları üstte tutun, gereksiz regex kullanmayın, basit string matching tercih edin Etki: Kural eşleştirme hızlanır, CPU kullanımı düşer, latency 10ms'den az kalır
Batch Processing	Öneri: Yüksek trafikli sistemlerde sayaç güncellemelerini batch olarak yapın, her istek için ayrı write yerine bufferda toplayın, 100-1000 istek biriktirip toplu yazın Etki: Cache write yükü %90 azalır, throughput 10x artar, cache sunucu ömrü uzar
Monitoring ve Tuning	Öneri: Quota metriklerini toplayın (usage rate, reset frequency), cache performansını izleyin, slow query'leri tespit edin, hotspot key'leri belirleyin Etki: Bottleneck'ler erken tespit edilir, proaktif scaling yapılır, SLA garantisi sağlanır

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Quota ve Throttling arasındaki fark nedir?	Throttling: Kısa sürede (saniye/dakika) hız sınırlaması. DDoS koruması ve burst control için. Quota: Uzun sürede (gün/ay) toplam kullanım limiti. Faturalama ve subscription yönetimi için. İkisi birlikte kullanılmalı: Throttling anlık koruma, Quota uzun dönem kontrol sağlar.
Genel	Bir API'ye hem Throttling hem Quota politikası eklenebilir mi?	Evet, kesinlikle önerilir. Örnek kombinasyon: Throttling: 100 istek/dakika (burst protection), Quota: 100.000 istek/ay (subscription limit). Her iki politika da bağımsız çalışır, birbirini tamamlar.
Teknik	SLIDING vs FIXED window hangisini seçmeliyim?	FIXED tercih edin çünkü: Faturalama döngüsüne uygun (her ayın 1'i sıfırlanır), daha performanslı, müşteriye daha net (kotanız X tarihinde yenilenecek), implementation daha basit. SLIDING sadece: Daha hassas kontrol gerekiyorsa, rolling period istiyorsanız (son 30 gün) kullanın.
Teknik	Cache sunucusu neden gereklidir?	Quota sayaçlarını merkezi olarak tutmak için Redis gereklidir. Dağıtık sistemlerde (birden fazla Gateway) her gateway aynı sayacı görmeli. Cache olmadan: Gateway'ler farklı sayarlar tutar, müşteri kotasını 2-3 kat fazla kullanabilir, fatura kayıpları oluşur.
Teknik	Kota verileri neden veritabanına da yazılıyor?	Cache yüksek performans sağlarken, veritabanı veri kalıcılığını garanti eder. Önemli nedenler: 1) Sistem yeniden başlatıldığında kota bilgileri kaybolmaz, 2) Raporlama ve analitik için geçmiş veriler saklanır, 3) Faturalama için güvenilir kayıt tutar, 4) Cache hatalarında fallback sağlar, 5) Yasal zorunluluklar için audit trail oluşturur. Veritabanı güncellemesi asenkron olduğu için API performansını etkilemez.
Kullanım	Müşteri kotasını ay ortasında artırırsam ne olur?	Politika güncellemesi yapın, yeni limit cache'e yazılır, mevcut kullanım korunur. Örnek: Müşteri 5000/10000 kullanmış, limiti 20000'e çıkarırsanız → 5000/20000 olur. Geriye dönük etkilemez, sadece ileriye etkiler.
Kullanım	Limiti değiştirdiğimde mevcut kullanımın ne olacağını veya reddedilen isteklerin kotaya dahil olup olmayacağını kontrol edebilir miyim?	Evet, Gelişmiş Ayarlar'daki iki bağımsız ayar bunu belirler. Limit Değişimi Davranışı, Kota Sayısı değeri değiştirildiğinde kullanım sayacını kontrol eder: varsayılanda (Dokunma) sayaç olduğu gibi bırakılır; sayacın önceki limite kırpılması ya da yalnız limit yükseltildiğinde sıfırlanması seçilebilir. Sayım Modu, politika tarafından reddedilen isteklerin kotayı tüketip tüketmeyeceğini kontrol eder: varsayılanda (Tüm istekler) tüketir, tarihsel davranışla aynıdır; Yalnızca kabul edilenler seçilirse reddedilen bir istek kotayı hiç tüketmez. Örnek: Bir müşterinin kotası 5 ve şimdiden 5 kabul + 5 red isteği yapmış, yani Tüm istekler modunda kullanım 10. Kota 8'e yükseltilirse, Önceki limite kırp davranışı kullanımı 5'e (önceki limite) indirir, böylece yeni limite ulaşılana kadar tam olarak 3 istek daha geçer.
Kullanım	Kota aşan müşteri ne zaman tekrar istek yapabilir?	Reset time'a kadar beklemeli. FIXED window'da: Bir sonraki periyot başında (örn: gelecek ayın 1'i). SLIDING window'da: İlk isteğin üzerinden periyot süresi geçince. Yanıt her zaman bir Retry-After başlığı (saniye) taşır — pencere kapanana kadar kalan süredir, en az 1'dir, platform geneli bir tavanla sınırlıdır (varsayılan 1 gün, aşağıdaki nota bakın) ve Rate Limit İstatistikleri ayarından bağımsız olarak eklenir. Rate limit header'ları aktifse response'da ayrıca X-RateLimit-Reset ile timestamp verilir.

Retry-After tavanı

Retry-After değeri platform genelinde bir tavanla sınırlıdır, böylece istemciye makul olmayan bir bekleme süresi bildirilmez. Bu özellikle aylık kotalar için önemlidir: tavan olmasaydı, gelecek ayın 1'inde sıfırlanan bir pencere yaklaşık 31 güne kadar bir bekleme süresi bildirebilirdi. Varsayılan tavan 1 gündür; Gateway (Worker) üzerinde apinizer.limit.retryAfterClampSeconds JVM sistem özelliği ile değiştirilebilir — geçersiz ya da pozitif olmayan bir değer varsayılana döner. Tavan sayacın kendisini etkilemez: erken bir tekrar denemesi yine aynı dolu pencereyle karşılaşır ve yine tavanla sınırlı, güncel bir Retry-After alır. Aynı tavan API Bazlı Daraltma politikasının Retry-After başlığı için de geçerlidir.