सर्वर API | Noxyr दस्तावेज़

API क्या देता है

API केवल-पढ़ने योग्य है और एक सर्वर तक सीमित है। यह status pages, spreadsheets और internal tools के लिए है, जो डैशबोर्ड के वही आँकड़े बिना login के चाहते हैं। यह सेटिंग्स नहीं बदल सकता, टिकट बंद नहीं कर सकता, या invoice नहीं बना सकता।

हर endpoint https://noxyrbot.com/api/v1 के अंतर्गत है और JSON लौटाता है। Key ही सर्वर की पहचान करती है, इसलिए कोई endpoint सर्वर ID नहीं लेता।

GET /api/v1/: इस key के लिए कौन से scopes चालू हैं और वह किन endpoints तक पहुँच सकती है।
GET /api/v1/server: नाम, आइकन, सदस्य संख्या, ऑनलाइन संख्या, boosts और बनने की तारीख।
GET /api/v1/tickets: कुल संख्या, खुले और बंद टिकट, 7 और 30 दिनों का आवागमन, और औसत रेटिंग।
GET /api/v1/activity?days=30: रोज़ के संदेश, joins और leaves, 90 दिन तक।
GET /api/v1/invoices: Invoice संख्या, मुद्रा के अनुसार आय और भुगतान स्थिति। invoice links scope के साथ, ?limit= डाउनलोड होने योग्य image URL वाले हाल के invoices जोड़ता है।
GET /api/v1/reviews: औसत रेटिंग, स्टार का विवरण और नवीनतम पाँच सार्वजनिक समीक्षाएँ।
GET /api/v1/giveaways: सक्रिय और समाप्त संख्या, कुल प्रविष्टियाँ और मौजूदा giveaways।

Key बनाना

हर सर्वर की एक key होती है। यह सर्वर के API पेज पर बनती है और एक बार दिखाई जाती है - केवल hash सहेजा जाता है, इसलिए खोई हुई key को दोबारा बनाना पड़ता है, जिससे पुरानी key बेकार हो जाती है।

डैशबोर्ड पर सर्वर खोलें और API पर जाएँ।
Generate दबाएँ और nxr_ से शुरू होने वाली key कॉपी करें। वह फिर नहीं दिखाई जाएगी।
जिस scope की ज़रूरत न हो उसे बंद करें। Invoice links डिफ़ॉल्ट रूप से बंद है, क्योंकि इससे ग्राहकों की invoice छवियाँ उजागर हो सकती हैं।
वैकल्पिक: Set up channel दबाएँ, ताकि बॉट सर्वर में endpoint सूची के साथ एक API category और channel बना दे।

पेज यह भी दिखाता है कि key आखिरी बार कब इस्तेमाल हुई और उसने कितने requests किए, जो लीक हुई key पहचानने का सबसे तेज़ तरीका है। टॉगल से इसे बंद करें, या पूरी तरह हटाने के लिए revoke करें।

Scopes

Scopes endpoints को नियंत्रित करते हैं, fields को नहीं। जिस endpoint का scope बंद है, उसके अनुरोध को 403 मिलता है, जिसके संदेश में scope का नाम होता है।

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Image links वाली हाल की invoice सूची जोड़ता है। डिफ़ॉल्ट रूप से बंद।
reviews: /reviews
giveaways: /giveaways

प्रमाणीकरण और उदाहरण अनुरोध

Key को Authorization header में Bearer token के रूप में भेजें। ब्राउज़र से कॉल की अनुमति है (CORS खुला है), लेकिन front-end कोड में रखी key सार्वजनिक key है, इसलिए API को ऐसे सर्वर से कॉल करें जिसे आप नियंत्रित करते हैं।

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
जवाब: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

दर सीमाएँ

हर key प्रति मिनट 60 requests कर सकती है। सीमा हर response में मानक RateLimit headers में लौटाई जाती है, और सीमा पार होने पर HTTP 429 मिलता है जिसकी error "rate_limited" होती है। डेटा बदलने से तेज़ poll न करें - टिकट और बिक्री के कुल आँकड़े हर मिनट पढ़ना काफ़ी है।

त्रुटियाँ

हर त्रुटि एक JSON है, जिसमें मशीन-पठनीय error code और मानव-पठनीय संदेश होता है।

401 अनधिकृत: Authorization header गायब है, Bearer token नहीं है, या key मौजूद नहीं है।
403 key_disabled: डैशबोर्ड पर यह key बंद की गई है।
403 scope_disabled: इस key के लिए वह scope बंद है।
404 not_found: अज्ञात endpoint। संदेश में मान्य endpoints की सूची होती है।
404 guild_unavailable: बॉट अब उस सर्वर में नहीं है।
429 rate_limited: एक मिनट में 60 से ज़्यादा requests।
500 internal_error: Noxyr की ओर से कुछ विफल हुआ। बाद में फिर कोशिश करें।