REST-API-Referenz
Die HTTP-API, die der Saba-chan-Daemon bereitstellt. Authentifizierungsverfahren und Katalog der wichtigsten Endpunkte.
REST-API-Referenz
Der Saba-chan-Daemon (saba-core) stellt auf 127.0.0.1:57474 eine HTTP-REST-API bereit. GUI und CLI rufen ausschließlich diese API auf, und Discord-Befehle, die über das Cloud-Relay eintreffen, werden von derselben Funktionalität im Daemon verarbeitet. Gegen denselben Vertrag können Sie einen eigenen Client bauen.
Diese Referenz fasst die Routen zusammen, die Benutzer oder Integratoren voraussichtlich brauchen, entnommen aus den Routendefinitionen des Daemons (src/ipc/). Einige interne Routen sind ausgelassen, und Feldschemata können sich ändern; maßgeblich ist der aktuelle Code.
1. Grundlagen
- Basis-URL:
http://127.0.0.1:57474(Standard). Änderbar über die UmgebungsvariableSABA_IPC_PORTodergui.ipcPortinconfig.json(wirksam nach einem Neustart des Daemons). - Bind-Adresse: Fest auf
127.0.0.1, daher von außen nicht erreichbar. Anfragen, derenHost-Header kein Loopback ist (127.0.0.1,localhost,::1), erhalten 403. - Authentifizierung: Jede Anfrage außer
/healthbenötigt den HeaderX-Saba-Token. Der Daemon erzeugt bei jedem Start ein neues Token und schreibt es in die Datei.ipc_tokenim Datenordner (Windows:%APPDATA%\saba-chan\.ipc_token). Ein fehlendes oder falsches Token führt zu 401 ohne Body. - Content-Type: Request-Bodys sind
application/json. Die meisten Antworten sind ebenfalls JSON (Ausnahmen: GUI-Bundles von Erweiterungen, Symbole usw.). - Fehlerformat: Unterscheidet sich je nach Route. Übliche Formen sind
{"error": "...", "error_code": "..."},{"success": false, "error": ..., "error_code": ...}und{"ok": false, "error": ...}. Manche Routen geben bei einem Fehler HTTP 200 mitok:falsezurück; prüfen Sie daher auch den Body.
2. Health-Check & Daemon
GET /health # kein Token erforderlich
GET /api/version
GET /api/diagnostics
GET /api/events # Ereignisstrom (SSE)
POST /api/daemon/shutdown
/health:{"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}.tokensagt nur, ob das gesendeteX-Saba-Tokenkorrekt ist; den Wert verrät es nie./api/version:{version, components: {...}}(Versionen von Kern, Modulen und Erweiterungen)./api/events: Server-Sent Events. Die wichtigsten Arten sindinstance.exit(Serverbeendigung / Absturzbefund),backup.done,update.available,schedule.warn,provision.progressundaction.run. Beim erneuten Verbinden können Sie verpasste Ereignisse über den HeaderLast-Event-IDoder?since=<n>nachholen./api/daemon/shutdown: Fährt den Daemon herunter.
3. Server (Instanzen)
Saba-chan verwaltet jeden Server als Instanz, identifiziert durch eine UUID (id).
3.1 Auflisten, Erstellen, Aktualisieren, Löschen
GET /api/servers # Serverliste + Laufzustand
GET /api/instances # Instanzliste
POST /api/instances # erstellen
PUT /api/instances/reorder # body: { "order": [id, ...] }
GET /api/instance/:id # Details (+ Zustimmungsstatus in agreements)
PATCH /api/instance/:id # Einstellungen ändern (Schlüssel-Wert-Objekt)
DELETE /api/instance/:id # löschen
POST /api/instance/:id/rename # body: { "name": "..." }
- Wichtigste Felder von
POST /api/instances:{ "name", "module_name", "port"?, "preset"?, "module_settings"?, "accept_agreements"?: [id] }. Bei Erfolg wird 201{success, id, ...}zurückgegeben, und definiert das Modul einen Installationsschritt, beginnt die Installation der Serverdateien im Hintergrund (§3.5). - Neben Port und Moduleinstellungen akzeptiert
PATCH /api/instance/:idauch Daemon-Einstellungen wie:auto_restart,restart_on_unknown_exit: ob nach einem Absturz / einem unbekannten Beenden automatisch neu gestartet wirdextra_args: zusätzliche Startargumente (eine Zeichenkette oder ein Array von Zeichenketten;nullleert sie)memory_limit_mb: Speicherlimit (MiB, mindestens 256; Formen wie"4G"/"4096M"werden akzeptiert;null/0bedeutet kein Limit). Gilt nur unter Windows.
- Zum Umbenennen muss der Server gestoppt sein; ein bereits verwendeter Name ergibt 409
name_taken.
3.2 Starten / Stoppen / Neustart
POST /api/instance/:id/start
POST /api/instance/:id/stop # optionaler body: { "force": true }
POST /api/instance/:id/restart # optionaler body: { "force": true }
GET /api/instance/:id/events # letzte Beendigungen
GET /api/server/:name/status # Status nach Name
- Vor dem Start prüft der Daemon die Zustimmung zu Bedingungen und führt die Prüfungen des Moduls aus. Fehlende Zustimmung ergibt 409
agreement_required(mitagreements); eine kritisch fehlgeschlagene Prüfung ergibt 409preflight_failed. - Beim Stoppen wird der ordnungsgemäße Stoppbefehl des Spiels gesendet, das Timeout des Moduls abgewartet (standardmäßig 30 Sekunden) und der Prozess zwangsweise beendet, wenn er noch läuft. Mit
force: truewird er sofort beendet. eventsgibt{events: [...]}mit dem Beendigungsbefund (user_stop,in_game_stop,crash,unknown_exit), den Belegen dafür, einem gegebenenfalls geplanten automatischen Neustart usw. zurück.
3.3 Konsole und Befehle
GET /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin # body: { "command": "say hello" }
POST /api/instance/:id/command # body: { "command": "<name>", "args"?: {...} }
GET /api/instance/:id/commands # für diesen Server verfügbare Befehle
POST /api/instance/:id/rest # reine REST-Spiele (z. B. Palworld)
POST /api/instance/:id/rcon # Kompatibilitätsname; nutzt den unten beschriebenen Befehlspfad (stdin → REST → RCON)
- Konsolenabfrage: Die Antwort ist
{success, lines: [{id, timestamp, source, content, level}], running, ...}. Mitsincewerden Zeilen zurückgegeben, derenidgrößer oder gleich diesem Wert ist; senden Sie beim nächsten Mal also die zuletzt erhalteneid+ 1. Ohnesinceerhalten Sie die letztencountZeilen (Standard 100). Der Daemon hält pro Server die letzten 10.000 Zeilen im Speicher. - Reihenfolge der Befehlspfade: stdin → REST → RCON. Befehle gehen zuerst an die Serverkonsole (stdin), und Spiele, die nur REST unterstützen, wie Palworld, laufen über REST. RCON wird nur für ein Spiel verwendet, dessen Modul
supported = ["rcon"]deklariert (keine Konsole und keine REST-API); der Daemon vergibt dann für jede Instanz einen eigenen Port und ein zufälliges Passwort und verbindet sich nur über Loopback (127.0.0.1). Andernfalls ist/rconein Pfad, der nur dem Namen nach für ältere Clients erhalten bleibt, und sendet an stdin. Server ohne Befehlspfad geben 409no_command_pathzurück. /stdingibt 409stdin_not_supportedzurück, wenn das Modul stdin nicht unterstützt./commandführt einen vom Modul definierten Befehl aus; ist der Server gestoppt, wird 409server_not_runningzurückgegeben.
3.4 Einstellungen, Bedingungen, Prüfungen
POST /api/instance/:id/launch-preview # body: { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements # body: { "accept": ["eula"] }
GET /api/instance/:id/properties # Konfigurationsdatei des Spiels lesen
PUT /api/instance/:id/properties # body: { "settings": {...} }
POST /api/instance/:id/validate # Serverprüfung
POST /api/instance/:id/diagnose # Protokollanalyse
launch-previewberechnet die Start-Befehlszeile, ohne den Server zu starten. Beispielantwort:{success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Passwortwerte werden als***maskiert. Deklariert das Modul keine Startargumente, wirdhas_launch_args: falsezurückgegeben.agreementshält die Zustimmung zu vom Modul deklarierten Bedingungen fest (z. B. Minecrafteula). Das funktioniert nur lokal; Anfragen aus entfernten Quellen (Discord usw.) erhalten 403agreement_local_only. Nicht deklarierte IDs erhalten 400invalid_format.
3.5 Installationsfortschritt und Spieleserver-Updates
GET /api/provision-progress/:name # :name = Instanzname
DELETE /api/provision-progress/:name # einen fehlgeschlagenen Fortschrittszustand schließen
GET /api/instance/:id/check-update
POST /api/instance/:id/apply-update
Beispielantwort von provision-progress:
{
"active": true,
"step": 2,
"total": 5,
"label": "...",
"message": "...",
"percent": 40,
"done": false,
"error": null
}
Läuft nichts, wird {"active": false} zurückgegeben. Ein erfolgreicher Fortschrittszustand wird nach 5 Sekunden automatisch gelöscht; ein fehlgeschlagener bleibt bestehen, bis Sie ihn mit DELETE schließen (wurde der Server gerade neu erstellt, wird er dann zurückgerollt). Der Fortschritt ist auch als provision.progress auf /api/events verfügbar.
apply-update gibt 409 server_running zurück, wenn der Server läuft. Vor dem Update wird ein Backup erstellt (bei Modulen, die Backups unterstützen).
3.6 Backups und geplante Aufgaben
GET /api/instance/:id/backups # { success, backups: [{ name, kind, created, size }] }
POST /api/instance/:id/backups # jetzt sichern
DELETE /api/instance/:id/backups/:name
POST /api/instance/:id/backups/:name/restore # Server muss gestoppt sein
GET /api/instance/:id/schedule
PUT /api/instance/:id/schedule # body: { "schedule": [...], "backup_keep"?: 10 }
- Backup-
kind:manual,scheduled,pre-update,pre-restore. Unterstützt das Modul keine Backups, erhalten Sie 400backup_unsupported; gibt es noch nichts zu sichern, 400nothing_to_back_up. - Das Wiederherstellen gibt 409
server_runningzurück, wenn der Server läuft, und der aktuelle Zustand wird vor dem Wiederherstellen alspre-restoregesichert. - Die Form einer geplanten Aufgabe:
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }
action ist backup | restart | announce | update, und Sie verwenden genau eines von every_minutes (alle N Minuten) und at (täglich um HH:MM). announce benötigt eine message, und warn_minutes gilt nur für restart und update. Ungültige Aufgaben ergeben 400 validation_failed (mit details).
4. Module
GET /api/modules # installierte Module
POST /api/modules/refresh # Modulordner neu einlesen
GET /api/module/:name # Modul-Metadaten
GET /api/module/:name/versions # installierbare Spieleserver-Versionen
GET /api/module/:name/locales
GET /api/modules/manifest # Katalog installierbarer Module
POST /api/modules/manifest/:id/install # ein Modul aus dem Katalog installieren
DELETE /api/modules/:id # ein Modul entfernen
Der Modulkatalog stammt aus der signierten Release-Liste, und heruntergeladene Dateien werden erst nach erfolgreicher Hash-Prüfung installiert.
5. Erweiterungen
GET /api/extensions # Liste mit Installations-/Aktivierungsstatus
POST /api/extensions/rescan
GET /api/extensions/manifest # Katalog installierbarer Erweiterungen
GET /api/extensions/updates
POST /api/extensions/:id/install
DELETE /api/extensions/:id
POST /api/extensions/:id/enable # führt den Hook daemon.startup asynchron aus
POST /api/extensions/:id/disable
GET /api/extensions/:id/config
PUT /api/extensions/:id/config
GET /api/extensions/:id/gui # GUI-Bundle (UMD-JavaScript)
GET /api/extensions/:id/gui/styles # CSS
GET /api/extensions/:id/i18n/:locale # ko / en / ja / ...
Fehler der Erweiterungsrouten haben die Form {success: false, error, error_code, ...}.
6. Einstellungen
GET /api/config/gui
PUT /api/config/gui # partielles JSON (flaches Zusammenführen)
GET /api/config/bot
PUT /api/config/bot # Bot-Einstellungen wie Präfix und Aliasse (partielles JSON)
GET /api/system/metrics # CPU, Speicher, Datenträger, Nutzung pro Server
Alle Benutzereinstellungen werden pro Namespace in einer einzigen Datei config.json im Datenordner gespeichert. Der Daemon synchronisiert die Bot-Einstellungen mit dem Relay. Der Discord-Bot selbst läuft auf dem Cloud-Relay, daher hat der Daemon keine API, um einen Bot-Prozess zu starten oder zu stoppen.
7. Updates
GET /api/updates/status # aktueller Zustand und Versionen pro Komponente
POST /api/updates/check # jetzt nach Updates suchen
POST /api/updates/download # optionaler body: { "components": [...] }
GET /api/updates/download/progress
POST /api/updates/apply # optionaler body: { "components": [...] }
POST /api/updates/launch-updater # per Installer anwenden (der Daemon stoppt)
GET /api/updates/config
PUT /api/updates/config
Update-Informationen stammen aus der signierten Release-Liste. Komponenten, deren laufende Dateien ersetzt werden müssen, werden in der Antwort von apply als gesondert anzuwenden markiert; ein Aufruf von launch-updater startet den Installer (saba-chan-installer --apply), der den Daemon stoppt, die Dateien ersetzt und nur das Geänderte wieder startet. Diese Routen antworten in der Form {ok: ...}.
8. Cloud-Relay-Pairing
Für den Pairing-Ablauf zwischen GUI und Relay-Server. Den ausführlichen Ablauf finden Sie auf der Seite Discord-Bot.
POST /api/relay/pair/initiate # einen Pairing-Code ausstellen (an das Relay weitergeleitet)
GET /api/relay/pair/:code/status # abfragen, ob das Pairing abgeschlossen ist
GET /api/relay/agent # Status des Relay-Agenten
POST /api/relay/agent/start
POST /api/relay/agent/stop
DELETE /api/config/node-token # das Node-Token dieses PCs löschen (stoppt den Agenten)
Sobald das Pairing abgeschlossen ist (status: "claimed"), speichert der Daemon das Node-Token automatisch und verbindet den Relay-Agenten mit dem neuen Token neu. Die Authentifizierung gegenüber dem Relay übernimmt der Daemon; Clients müssen sich nicht darum kümmern.
9. Authentifizierungsbeispiel (curl)
TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")
curl -H "X-Saba-Token: $TOKEN" \
http://127.0.0.1:57474/api/servers
curl -X POST \
-H "X-Saba-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"command":"list"}' \
http://127.0.0.1:57474/api/instance/<instance-id>/stdin
<instance-id> ist die id aus der Antwort von GET /api/servers oder GET /api/instances.
10. Versionskompatibilität
- Diese API gilt als privates IPC. Sie ist kein öffentlicher Vertrag; Pfade und Schemata können sich daher auch in Nebenversionen ändern.
- Wenn Sie einen eigenen Client verteilen, prüfen Sie die Daemon-Version (
versionausGET /health) und gehen Sie konservativ damit um.
Bei Problemen siehe Fehlerbehebung.