API Kullanım Skorları

Her API çağrısı, çağrıldığı endpoint'in skoruna eşit puan tüketir. Puanlar client başına aylık olarak monthly_limit altında toplanır; limit aşıldığında middleware yanıtı HTTP 429 ile keser.

Bir çağrı gerçekte ne tüketir

GET /v2/health ücretsizdir. Diğer her endpoint 1000 puan tüketir.

Sözleşme olarak bunu kabul edin. Üzerine endpoint bazlı maliyet varsayımı kurmayın — bütçenizi her zaman gerçeği raporlayan X-MonthlyLimit-* başlıklarıyla yönetin.

Bugün neden sabit oran

UsageLimit middleware'i her isteği sunucu tarafındaki usage.EndpointScores haritasında (contexts/integration/aggregates/usage/usage.go) <METHOD> <route şablonu> anahtarıyla arar; eşleşme yoksa DefaultScore = 1000'e düşer. Arama, eşleşen route kalıbıyla (/v2/admin/tokens/:tokenID/burn) yapılır; yani parametreli uçlar da doğru çözülür.

Dolayısıyla sabit oran bir kusur değil, bir fiyatlandırma kararıdır: haritada listelenen her uç şu an DefaultScore ile fiyatlanmış durumda, yani listelenmiş bir uç çağırana listelenmemiş biriyle tam olarak aynıya mal oluyor. Sonucu değiştiren tek girdi GET /v2/health.

İleride uçlar farklı fiyatlandırılırsa yalnızca harita değişir — arama zaten doğru anahtarı çözüyor.

Aylık sayaç

• Sayaç Redis'te monthly-usage-{clientID}-{YYYY-MM} anahtarı altında tutulur.
• Cache miss durumunda MongoDB'deki usages koleksiyonundan toplanıp yeniden cache'lenir. Meşru sıfır ile cache miss ayrımı *int64 döndürülerek yapılır; böylece 0 puan harcamış bir client her istekte Mongo'ya düşmez.
• Her başarılı istekten sonra sayaç o isteğin skoru kadar artar.
• Aylık limit aşıldığında middleware şunu üretir:
  • HTTP 429 Too Many Requests
  • X-MonthlyLimit-Limit, X-MonthlyLimit-Used, X-MonthlyLimit-Remaining başlıkları
  • Sayaç gelecek ayın başında sıfırlanır (YYYY-MM anahtarı değişir).

Kalan bütçeyi okumak

Aşağıdaki başlıklar her yanıtta gelir. Canlı sayaçtan hesaplandıkları için, puanlama nasıl yapılandırılırsa yapılandırılsın doğru kalırlar:

Başlık	Anlamı
X-MonthlyLimit-Limit	Client'ın aylık puan hakkı
X-MonthlyLimit-Used	Bu ay şimdiye kadar tüketilen puan
X-MonthlyLimit-Remaining	İstekler 429 dönmeye başlamadan önce kalan puan

429 yanıtı

{
    "code": 10029,
    "domain": 20,
    "message": "monthly usage limit exceeded"
}

Notlar

• Skorlar client başınadır; kullanıcı ya da node başına değil.
• Doğrulamadan geçemeyen bir istek de middleware'e ulaşır ve sayılır.
• İleride endpoint bazlı fiyatlandırma gelirse yalnızca haritadaki skorlar değişir; anahtarlar zaten gerçek route'ları adlandırıyor ve arama onları zaten çözüyor. O zamana kadar tasarım yapılacak tek davranış yukarıdaki sabit orandır.