API Kullanım Skorları

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

Skor Lookup Sözleşmesi

UsageLimit middleware'i her isteği sunucu tarafındaki usage.EndpointScores tablosundan arar:

• Anahtar formatı: <METHOD> <templated_path> (örn. GET /v2/tokens/:tokenID).
• Eşleşme bulunursa, kayıttaki tam sayı puan tüketilir.
• Eşleşme yoksa, DefaultScore = 1000 uygulanır.

/v2/health haricinde her endpoint pratikte ya tabloda 1000 olarak tanımlıdır, ya da default 1000'e düşer; bu yüzden bir partner için "her çağrı 1 birim tüketir" gibi düşünmek doğru bir yaklaşım. Daha pahalı group_search benzeri uçların gelecekte 2000 olarak tanımlanması planlandığı için, kullanıcı tarafında bu tabloyu sertleştirmemenizi öneririz — limit yönetimini X-MonthlyLimit-* header'ları üzerinden yapın.

Bilinen tutarsızlık

Production middleware bugün c.Request().URL.Path (literal path, örn. /v2/tokens/68ae.../listing) ile lookup yapmaktadır; EndpointScores anahtarları ise templated path (/v2/tokens/:tokenID/listing) ile yazılmıştır. Bu yüzden tabloda explicit puanı tanımlı endpoint'ler bile bugün için DefaultScore = 1000'e düşer. Lookup'ı c.Path() ile yapmak veya path'i normalize etmek henüz uygulanmadığında pratik etki şudur: /v2/health dışındaki tüm endpoint'ler 1000 puan tüketir. Yeni puanlama planlandığında bu davranış kullanıcıya görünür biçimde değişebilir.

Aylık Skor Sayacı

• Sayaç Redis'te monthly-usage-{clientID}-{YYYY-MM} anahtarı altında tutulur.
• Cache miss durumunda sayaç MongoDB'deki usages koleksiyonundan toplanıp yeniden cache'lenir (cache hit'lerinde legitimate zero ile cache miss ayrımı *int64 döndürmek üzere yapılır — yani 0 puan kullanan client her seferinde Mongo'ya düşmez).
• Her başarılı API isteği sonrası sayaç o isteğin skoru kadar arttırılır.
• Aylık limit aşıldığında middleware aşağıdaki yanıtı üretir:
  • HTTP 429 Too Many Requests
  • X-MonthlyLimit-Limit, X-MonthlyLimit-Used, X-MonthlyLimit-Remaining header'ları
  • Sayaç gelecek ayın başında otomatik olarak sıfırlanır (YYYY-MM anahtarı değişir).

Endpoint Skor Tablosu

Aşağıdaki tablo usage.EndpointScores haritasının canlı görüntüsüdür. Listede olmayan her endpoint DefaultScore = 1000'e düşer. Templated path'ler :nodeID, :tokenID gibi parametre yer tutucularını gösterir.

Health

Endpoint	Method	Skor
/v2/health	GET	0

Authentication

Endpoint	Method	Skor
/v2/oauth/token	POST	1000

Nodes

Endpoint	Method	Skor
/v2/nodes/root	GET	1000
/v2/nodes/:nodeID	GET	1000
/v2/nodes	POST	1000
/v2/nodes/:nodeID	PUT	1000
/v2/nodes/:nodeID	DELETE	1000
/v2/nodes/:nodeID/contract/status	GET	1000
/v2/nodes/:nodeID/summary	GET	1000
/v2/nodes/:nodeID/children/search	POST	1000
/v2/nodes/:nodeID/deploy/contracts	POST	1000

Tokens

Endpoint	Method	Skor
/v2/tokens/:tokenID	GET	1000
/v2/tokens/:tokenID	PUT	1000
/v2/tokens/:tokenID	DELETE	1000
/v2/tokens/:tokenID/metric	PUT	1000
/v2/tokens/node/:nodeID	POST	1000
/v2/tokens/node/:nodeID/search	POST	1000
/v2/tokens/:tokenID/rent	POST	1000
/v2/tokens/:tokenID/listing	POST	1000
/v2/tokens/:tokenID/delist	POST	1000
/v2/tokens/:tokenID/passive	POST	1000
/v2/tokens/:tokenID/burn	POST	1000
/v2/tokens/:tokenID/public-transfer	POST	1000
/v2/tokens/:tokenID/open-to-otc	POST	1000
/v2/tokens/:tokenID/open-to-secondary-market	POST	1000
/v2/tokens/:tokenID/transactions/search	POST	1000

Fees

Endpoint	Method	Skor
/v2/fees/nodes/:nodeID	GET	1000
/v2/fees/nodes/:nodeID	POST	1000
/v2/fees/nodes/:nodeID/platform	GET	1000
/v2/fees/nodes/:nodeID/platform	POST	1000
/v2/fees/:id/nodes/:nodeID	PUT	1000
/v2/fees/:id/nodes/:nodeID/platform	PUT	1000

Categories

Endpoint	Method	Skor
/v2/categories/root	GET	1000
/v2/categories/:categoryID	GET	1000
/v2/categories/:categoryID/children/search	POST	1000

Supervisors

Endpoint	Method	Skor
/v2/supervisors/nodes/:nodeID	GET	1000

Diğer Endpoint'ler

EndpointScores tablosunda yer almayan tüm endpoint'ler (purchases, OTC, secondary-markets, users CRUD, KYC, vb. dahil) default 1000 skor tüketir. Aşağıdaki uç başlıkları örnektir — listede olup olmamaları aktif skoru değiştirmez:

• /v2/users/users/... (user CRUD ve wallet)
• /v2/users/tokens/... (kullanıcı token okuma, burn)
• /v2/users/purchases/...
• /v2/users/secondary-markets/...
• /v2/users/otcs/...
• /v2/admin/... (admin tarafı uçları — admin context backend'inde çalışır, integration scoring tablosu admin path'lerini açıkça içermez)

Belirli bir uca özel puanlama planlanıyorsa usage.EndpointScores haritasına eklenmelidir; ardından middleware'i template path lookup'a geçirmek gerekir (bkz. yukarıdaki uyarı kutusu).

Hata Yanıtı

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-MonthlyLimit-Limit: 100000
X-MonthlyLimit-Used: 100000
X-MonthlyLimit-Remaining: 0
Retry-After: 1209600

{
  "code": -1,
  "domain": 0,
  "message": "monthly_limit_exceeded"
}

Retry-After saniye cinsindendir ve içinde bulunulan ayın sonuna kadar bir tahmindir.

Pratik Öneriler

• X-MonthlyLimit-Remaining header'ını client tarafında izleyin; 429'a girmeden quota artırma talebi açın.
• Sıfır skorlu (/v2/health) probe endpoint'lerini canlılık kontrolleri için seçin; bunlar quota'yı yemez.
• Bulk işlemlerde mümkünse */search uçlarını paginasyon ile çağırın — tek tek GET çağırmaya kıyasla aynı skor maliyetiyle daha az çağrı yapmış olursunuz.