Game-Host-API

Der Teil der API des Panels, den Integrationen verwenden: Dateien eines Servers lesen und schreiben, Befehle senden, die Konsole live verfolgen und den Server ein- und ausschalten.

Jeder Endpoint mit seinen Parametern: die API-Referenz (Englisch), erzeugt aus dem OpenAPI-Dokument des Panels. Jedes Panel liefert es auch unter /openapi/v1.json aus, zum Durchblättern unter /api/docs.

Grundlagen

• Anmeldung mit einem API-Token: Authorization: Bearer ….
• Alle Server-Pfade beginnen mit /api/v1/tenants/{tenantId}/servers/{serverId}.
• Fehler kommen als application/problem+json mit einem stabilen code.

Endpoints

Methode und Pfad	Berechtigung	Hinweise
GET (der Pfad selbst)	server.view	state: installing · installFailed · offline · starting · running · stopping. allocations[] enthält role (game, query, rcon …), ip, port, protocol, address. stats enthält CPU, Arbeitsspeicher, Speicherplatz, Uptime. permissions[] ist, was der Aufrufer darf.
POST /power { "action": "start" }	power.<action>	start, stop, restart, kill. 409 invalid_state während der Installation.
POST /command { "command": "say hi" }	console.write	409 invalid_state, wenn der Server nicht läuft.
POST /rcon { "command": "list" }	console.write	Liefert { "response": "…" }, für Spiele mit RCON.
GET /console/stream	console.read	Server-Sent Events, siehe unten.
GET /console/log	console.read	Das ganze Konsolen-Log als Datei.
GET /metrics?range=1h	monitor.view	Mittelwerte pro Minute; 1h, 6h, 24h oder 7d.
GET /files?path=/config	files.list	Nur Einträge, auf die der Aufrufer zugreifen darf.
GET /files/content?path=whitelist.txt	files.read	Bis 4 MiB, zum Bearbeiten. ETag: "<sha256>", X-File-Size, X-File-Truncated.
GET /files/download?path=world.zip	files.read	Jede Grösse, gestreamt.
GET /files/archive?path=/world	files.list	Ein Ordner als Zip, mit den Dateien, die der Aufrufer lesen darf. names= (mehrfach möglich) wählt Einträge des Ordners.
PUT /files/content?path=whitelist.txt	files.write	Der Body ist der neue Inhalt. Bedingungen siehe unten. Grosse Dateien in Teilen: &offset=<position>&final=false, der letzte Teil mit final=true.
DELETE /files?path=…	files.delete
POST /files/delete { "paths": [] }	files.delete pro Pfad	Liefert { "done", "failed": [{ "path", "error" }] }.
POST /files/move { "paths": [], "to": "/old" }	files.write auf beiden Pfaden	Antwort wie beim Löschen.
POST /files/rename { "from", "to" }	files.write auf beiden Pfaden
POST /files/directory { "path" }	files.write

Fehler

Status	code
400	invalid_action, variable_invalid, range_invalid
401	Token fehlt, ist ungültig, widerrufen oder abgelaufen, oder falsches Netzwerk
403	forbidden (der Server existiert für dich, aber diese Aktion oder dieser Pfad ist nicht erlaubt), token_not_allowed
404	Server unbekannt, oder gar keine Berechtigung darauf
409	node_offline (der Agent des Nodes ist nicht verbunden), invalid_state
412	precondition_failed

Sicheres Lesen, Ändern, Schreiben

Für Dateien, die eine Integration verwaltet, etwa eine Whitelist, damit sie nie die Änderung von jemand anderem überschreibt:

1. GET  …/files/content?path=whitelist.txt        → Inhalt + ETag "abc…"
2. neuen Inhalt berechnen
3. PUT  …/files/content?path=whitelist.txt         If-Match: "abc…"
4. bei 412: jemand hat die Datei inzwischen geändert → zurück zu 1

If-None-Match: * schreibt nur, wenn die Datei noch nicht existiert.

Konsolen-Stream (SSE)

GET …/console/stream sendet text/event-stream:

event: state
data: {"state":"running"}

event: console
data: {"lines":["[12:00:01] Done (3.9s)!"],"history":true}

event: console
data: {"lines":["<Steve> hello"]}

: keep-alive

• Beim Verbinden: der aktuelle Zustand, dann der jüngste Verlauf (markiert mit "history": true), dann Live-Events.
• Keep-alive: alle 15 Sekunden ein Kommentar.
• Neu verbinden, wenn die Verbindung abbricht. Der Verlauf wird erneut gesendet; entferne Duplikate, falls dein Anwendungsfall das braucht.
• Hinter nginx: Das Panel sendet X-Accel-Buffering: no.