API ציבורי
API HTTP קטן לקריאה בלבד לאחזור סטטוס שרתים מחוץ לפאנל: לוח מחוונים לסטטוס, צג זמינות, בוט Discord, כלל אוטומציה ביתית. הוא מוגש על ידי הפאנל עצמו ומחזיר את אותם נתונים חיים שהדפים של הפאנל מציגים (מהמטמון בזיכרון), כך שסקר שלו לעולם לא נוגע ב-Docker.
הוא כבוי עד שמנהל מערכת ישתמש בו ומוגן על ידי מנהל מערכת. שום דבר לא נחשף עד שקיים אסימון.
הפעלתו
Section titled “הפעלתו”הגדרות → API ציבורי → מפתח חדש. תן לו שם, בחר מה הוא יכול לראות (כל השרתים, או קבוצה ספציפית), ואופציונלית תאריך תפוגה. המפתח המלא (אסימון Bearer) מוצג פעם אחת, בדיאלוג; העתק אותו כעת, מכיוון שרק קידומת קצרה נשמרת לאחר מכן, לצורך זיהוי ברשימה.

יצירת המפתח הראשון מפעילה את ה-API באופן אוטומטי (המתג אפשר לאפליקציות חיצוניות לקרוא סטטוס הוא בקרת השהיה: כבה אותו כדי להפסיק הגשה מבלי לבטל מפתחות כלשהם). בטל מפתח מהטבלה זהה בכל עת; לקוחות המשתמשים בו מאבדים גישה באופן מיידי.
אסימונים מאוחסנים כגיבוב SHA-256 (לעולם לא בטקסט רגיל), שורדים הפעלה מחדש של הפאנל, וחַיִּים יותר מהשרתים שהם מוגבלים אליהם (שרת שנמחק פשוט יוסר מתוצאות האסימון הזה).
שלח את האסימון כאישור Bearer:
Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxאין עוגיות ואין CORS: זה מיועד לשרת-לשרת ולקריאות CLI, לא לאפליקציות דפדפן ממקור אחר. אם הפאנל נמצא מאחורי פרוקסי הפוך, ודא שהפרוקסי מעביר את כותרת ה-Authorization.
כשלונות מחזירים 401 עם { "ok": false, "error": "..." }. כל דבר שאינו GET (או HEAD) מחזיר 405. נתיבים לא ידועים מחזירים 404. כאשר ה-API מושבת, כל נתיב מחזיר 404.
מגבלת קצב
Section titled “מגבלת קצב”כל אסימון מקבל תקציב משלו, RATE_LIMIT_PUBLIC_API_PER_MIN (ברירת מחדל 120 בקשות/דקה; 0 משבית את המגבלה). מעבר למגבלה מחזיר 429. כל בקשה, עוד לפני שהאסימון שלה נבדק, נספרת גם כן כנגד מכסה לכל IP של לקוח, פי חמישה מהמספר הזה, כך שסריקה עם אסימונים חסרים, פגומים, שבוטלו או שתוקפם פג, לא יכולה לעקוף את התקציב על ידי סיבובם.
נקודות קצה
Section titled “נקודות קצה”GET /api/v1/servers
Section titled “GET /api/v1/servers”כל שרת שהאסימון מוגבל אליו.
{ "ok": true, "total": 1, "online": 1, "servers": [ { "id": "srv_ab12cd34", "name": "SMP", "type": "PAPER", "state": "running", "cpuPct": 18.4, "memoryMb": 2048, "memoryLimitMb": 4096, "uptimeSeconds": 11722, "players": { "online": 3, "max": 20 } } ]}GET /api/v1/servers/:id
Section titled “GET /api/v1/servers/:id”שרת אחד, אותו אובייקט תחת מפתח server. מחזיר 404 עבור מזהה לא ידוע וגם עבור שרת שהאסימון אינו מוגבל אליו (אין אורקל קיום), ו-400 עבור מזהה פגום.
שדות תגובה
Section titled “שדות תגובה”| שדה | משמעות |
|---|---|
total |
כמה שרתים גלויים לאסימון זה (לאחר סינון ההיקף שלו). |
online |
כמה מהם במצב: running. |
id |
מזהה שרת יציב (srv_...). |
name |
שם תצוגה. |
type |
סוג שרת itzg (PAPER, FABRIC, AUTO_CURSEFORGE, …). |
state |
running, starting, stopped, או crashed: סיכום יציב של הסטטוס הפנימי של הפאנל. |
cpuPct |
אחוז CPU אחרון, או null כאשר השרת אינו פועל. |
memoryMb |
זיכרון תושב ב-MB, או null. |
memoryLimitMb |
מגבלת זיכרון מוגדרת של הקונטיינר ב-MB, או null. |
uptimeSeconds |
שניות מאז שהקונטיינר הופעל, או null. |
players |
{ online, max }, או null עד שהשרת מדווח על רשימת שחקנים. |
curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq