Kunden-API Dokumentation

Verbinde deine Anwendungen mit MarvinMC Hosting ueber gezielt berechtigte API-Schluessel.

Schnellstart

Erstelle unter Sicherheit > API-Schluessel einen Schluessel, waehle Server und Rechte und authentifiziere dich mit Authorization: Bearer <key>. Verwende HTTPS. Schluessel beginnen mit mmc_ und werden nur einmal angezeigt. Niemals in URLs, oeffentlichem JavaScript oder Repositories ablegen.

Anwendungen können auch ausdrücklich freigegebene OAuth-Serverrechte verwenden. Verfügbare Endpunkte und Scopes unterscheiden sich von persönlichen API-Schlüsseln: Serverfreigaben und Hosting-API

Basis-URL: https://hosting.marvinmc.net/api/client/v1

Setze MMC_API_KEY in deiner lokalen Umgebung auf deinen geheimen Schluessel, bevor du die Beispiele ausfuehrst.

curl --fail-with-body 'https://hosting.marvinmc.net/api/client/v1/servers' \
  -H "Authorization: Bearer $MMC_API_KEY"

{
    "servers": [
        {
            "id": "1234567890123456789",
            "name": "EXAMPLE_SERVER"
        }
    ]
}

Beispielantwort mit Platzhaltern. Ersetze SERVER_ID durch eine ID aus deiner eigenen Serverliste. Die folgende Anfrage sendet einen echten Konsolenbefehl.

curl --fail-with-body -X POST 'https://hosting.marvinmc.net/api/client/v1/servers/SERVER_ID/command' \
  -H "Authorization: Bearer $MMC_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"command":"say hi"}'

Zugriff und Limits

Drei Voraussetzungen muessen erfuellt sein: ein API-freigeschalteter Servertyp, Zugriff auf den Server und das passende Schluesselrecht. Free-Server sind fuer die Kunden-API gesperrt. Gesperrte Server fehlen in Listen; direkte Abfragen erhalten HTTP 403 mit api_disabled. Alte Schluessel umgehen keine spaetere Tarif-Sperre. Browser-Sitzungen sind von Kunden-API-Schluesseln getrennt.

Schluessel erben keine Adminrechte. Erstellen und Bearbeiten erfordern Passwort oder Zwei-Faktor-Code. Entfernte Server, eingeschraenkte Rechte, Widerruf oder Passwortwechsel entziehen den entsprechenden Zugriff. Laufzeit: 1 bis 365 Tage; maximal 20 aktive Schluessel pro Account. Bereits laufende Aktionen koennen noch abschliessen; wartende werden vor Ausfuehrung erneut geprueft.

60 Anfragen pro Minute und Schluessel, zusaetzlich 600 je IP. HTTP 429 enthaelt Retry-After: 60. Warte vor erneuten Versuchen und vergroessere bei Fehlern den Abstand. Maximal 1 MiB JSON pro Anfrage. Anfrage-Metadaten bleiben 30 Tage gespeichert, ohne Tokens oder Anfrageinhalte.

server.read: Status und Auslastung lesen
console.read: Konsole lesen
console.write: Konsolenbefehle senden
power: Starten, stoppen, neustarten und beenden
files.read: Dateien lesen und durchsuchen
files.write: Textdateien bearbeiten
backups.read: Backups auflisten
backups.create: Backups erstellen

Endpunkte

GET/servers

Server auflisten

Liefert servers mit id und name. Enthalten sind nur ausgewaehlte, zugaengliche und API-freigeschaltete Server.

Benoetigtes Recht: Ausgewaehlte zugaengliche Server

200 Anfrage erfolgreich abgeschlossen.

GET/servers/{id}/stats

Serverstatistik abfragen

Liefert aktuellen Zustand und Node-Statistiken. Verfuegbare Messwerte haengen von der Laufzeitumgebung ab.

Benoetigtes Recht: server.read

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.

200 Anfrage erfolgreich abgeschlossen.

GET/servers/{id}/console

Konsole lesen

Liefert logs, log_cursor, log_mode und log_reset mit aktuellem Zustand und Statistiken. Der erste Ausschnitt ist auf die letzten 500 Zeilen / 256 KiB begrenzt; danach koennen nur neue Zeilen abgefragt werden. Ein ausgeschalteter Server hat keine aktive Konsolenausgabe.

Benoetigtes Recht: console.read

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.
cursorOptional: Unveraenderter log_cursor der vorherigen Antwort. Fuer den ersten Ausschnitt weglassen. Logs nur anhaengen, wenn log_mode delta und log_reset false ist.

200 Anfrage erfolgreich abgeschlossen.

POST/servers/{id}/command

Konsolenbefehl senden

Sendet an die echte Serverkonsole. /say hi wird zu say hi; //say hi wird zu /say hi. Erfordert einen laufenden kompatiblen Server.

Benoetigtes Recht: console.write

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.

JSON-Anfrageinhalt

{
    "command": "say hi"
}

200 Anfrage erfolgreich abgeschlossen.

POST/servers/{id}/power

Serverzustand aendern

Stellt Start, Stop, Neustart oder Kill als Auftrag ein. Kill beendet sofort. CAPTCHA-pflichtige Aktionen muessen im Webpanel ausgefuehrt werden.

Benoetigtes Recht: power

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.
Idempotency-KeyOptional: Sende fuer eine neue Power- oder Backup-Aktion einen eindeutigen Idempotency-Key mit maximal 200 Zeichen. Nur fuer die Wiederholung derselben Aktion wiederverwenden. Du erhaeltst dann denselben Auftrag statt einer doppelten Ausfuehrung. Gueltig waehrend der Aufbewahrungszeit des Auftrags (90 Tage bei abgeschlossenen Auftraegen).

JSON-Anfrageinhalt

{
    "action": "restart"
}

202 Auftrag angenommen, Ausfuehrung steht noch aus.

GET/servers/{id}/files

Verzeichnis auflisten

Listet Dateien und Ordner unter path, standardmaessig /server. Keine rekursive Inhaltsliste.

Benoetigtes Recht: files.read

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.
pathOptional: Pfad ab dem Dateiverzeichnis des Servers, zum Beispiel /server/server.properties oder /backups. Werte in Query-Parametern URL-kodieren.

200 Anfrage erfolgreich abgeschlossen.

GET/servers/{id}/file

Textdatei lesen

Liefert eine Textdatei zum Bearbeiten, keinen Binaerdownload. Bestehende Editor-Groessenlimits und Dateirechte gelten weiter.

Benoetigtes Recht: files.read

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.
pathErforderlich: Pfad ab dem Dateiverzeichnis des Servers, zum Beispiel /server/server.properties oder /backups. Werte in Query-Parametern URL-kodieren.

200 Anfrage erfolgreich abgeschlossen.

PUT/servers/{id}/file

Textdatei speichern

Schreibt content nach path. Bestehende Datei-, Speicher- und Auftragssperren gelten weiter. Kein Endpunkt fuer Binaeruploads.

Benoetigtes Recht: files.write

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.

JSON-Anfrageinhalt

{
    "path": "/server/example.txt",
    "content": "example"
}

200 Anfrage erfolgreich abgeschlossen.

GET/servers/{id}/search

Dateien rekursiv suchen

Liefert entries mit path, directory und bei Texttreffern line und snippet. Seiten anhaengen und next_cursor folgen, bis er null ist. Eine leere Seite beendet die Suche nicht, solange next_cursor vorhanden ist. total_scanned zeigt den Fortschritt, skipped nicht lesbare Dateien/Ordner oder das Tiefenlimit. limited kennzeichnet laufende oder unvollstaendige Ergebnisse. Pro Anfrage: 100 Treffer, 20.000 Suchschritte, 2,5 Sekunden, 16 MiB Text. Textdateien bis 512 KiB, maximale Tiefe 24, keine Symlink-Verfolgung. Bei Dateiaenderungen doppelte Pfade zusammenfassen. API-Ratenlimits gelten fuer jede Seite.

Benoetigtes Recht: files.read

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.
pathOptional: Pfad ab dem Dateiverzeichnis des Servers, zum Beispiel /server/server.properties oder /backups. Werte in Query-Parametern URL-kodieren.
queryErforderlich: Suchbegriff mit 2 bis 100 Zeichen.
contentOptional: 0 sucht nur Namen; 1 durchsucht zusaetzlich begrenzte Textinhalte.
cursorOptional: Unveraenderter next_cursor der vorherigen Suchantwort. path, query und content beibehalten. Verfaellt nach 30 Minuten. Fuer eine neue Suche weglassen.

200 Anfrage erfolgreich abgeschlossen.

GET/servers/{id}/backups

Backups auflisten

Liefert vorhandene Backups und Angaben zum Backupspeicher unter Beachtung der Serverrechte.

Benoetigtes Recht: backups.read

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.

200 Anfrage erfolgreich abgeschlossen.

POST/servers/{id}/backups

Backup erstellen

Stellt ein tar.gz-Backup mit Zeitstempelnamen als Auftrag ein. Bei laufendem Server sind confirm_stop=true und der Scope power erforderlich. Er wird fuer das Backup gestoppt und nach Erfolg wieder gestartet, sofern nicht abgelaufen. Ohne Bestaetigung sind nur Offline-Backups erlaubt. Das Speicherlimit bleibt verbindlich.

Benoetigtes Recht: backups.create

idErforderlich: Deine Server-ID als Zeichenkette, nicht als JavaScript-Zahl.
Idempotency-KeyOptional: Sende fuer eine neue Power- oder Backup-Aktion einen eindeutigen Idempotency-Key mit maximal 200 Zeichen. Nur fuer die Wiederholung derselben Aktion wiederverwenden. Du erhaeltst dann denselben Auftrag statt einer doppelten Ausfuehrung. Gueltig waehrend der Aufbewahrungszeit des Auftrags (90 Tage bei abgeschlossenen Auftraegen).

JSON-Anfrageinhalt

{
    "confirm_stop": true
}

202 Auftrag angenommen, Ausfuehrung steht noch aus.

GET/jobs/{id}

Auftrag abfragen

Liefert Status, Phasen, Zeitstempel und ggf. Fehler/Referenz. Nur der erstellende API-Schluessel darf abfragen. Sein aktueller Servertyp, das Schluesselrecht und der Serverzugriff muessen weiterhin passen.

Benoetigtes Recht: same_key_as_job_submission

idErforderlich: Die bei Auftragserstellung erhaltene Auftrags-ID als Zeichenkette.

200 Anfrage erfolgreich abgeschlossen.

Hintergrundauftraege

Power-Aktionen und Backup-Erstellung antworten mit HTTP 202 und einem job-Objekt. Frage GET /jobs/{id} mit demselben Schluessel ab, zum Beispiel alle 5 Sekunden, bis succeeded, failed, canceled oder interrupted erreicht ist. HTTP 202 bestaetigt noch nicht die erfolgreiche Ausfuehrung. job_url oeffnet das Webpanel; JSON erhaeltst du unter /jobs/{id} relativ zur API-Basis. Das Antwortbeispiel unten ist gekuerzt.

Sende fuer eine neue Power- oder Backup-Aktion einen eindeutigen Idempotency-Key mit maximal 200 Zeichen. Nur fuer die Wiederholung derselben Aktion wiederverwenden. Du erhaeltst dann denselben Auftrag statt einer doppelten Ausfuehrung. Gueltig waehrend der Aufbewahrungszeit des Auftrags (90 Tage bei abgeschlossenen Auftraegen).

{
    "job": {
        "id": "JOB_ID",
        "status": "queued",
        "url": "/?member=jobs&job=JOB_ID"
    },
    "job_url": "/?member=jobs&job=JOB_ID"
}

queued: Wartend
running: Wird ausgefuehrt
succeeded: Abgeschlossen
failed: Fehlgeschlagen
canceled: Abgebrochen
interrupted: Pruefung durch Administrator erforderlich

Antworten und Fehler

200: Anfrage erfolgreich abgeschlossen.
202: Auftrag angenommen, Ausfuehrung steht noch aus.
400: Ungueltige Anfrage oder Aktion fehlgeschlagen. Beachte das Feld error.
401: API-Schluessel fehlt, ist ungueltig, abgelaufen oder widerrufen.
403: Servertyp, Accountrechte, Schluesselrechte oder CAPTCHA-Regel verweigern den Zugriff.
404: Unbekannter API-Endpunkt.
409: Fuer diesen Server ist bereits eine Aktion aktiv.
429: Anfragelimit erreicht. Beachte Retry-After.

{"error":"api_disabled"}

Fehler enthalten das maschinenlesbare Feld error. api_disabled bedeutet Tarif-Sperre; server_permission bedeutet fehlender Serverzugriff oder fehlendes Schluesselrecht; captcha verlangt das Webpanel. Auftragsfehler koennen eine Supportreferenz enthalten. Berechtigungsfehler und destruktive Aktionen nicht blind wiederholen.