API-Referenz
API-Referenz
Die Webgune-API ist eine REST-API in JSON. Es gibt zwei Oberflächen:
https://api.webgune.cloud/api/*wird intern vom Dashboard verwendet, nicht versioniert.https://api.webgune.cloud/api/v1/*ist die öffentliche Oberfläche, stabil, für Integrationen von Drittanbietern gedacht (CI/CD, Skripte, Ihr eigenes Tooling). Verwenden Sie diese.
Die interaktive Referenz, generiert aus dem OpenAPI-Spec (GET /api/v1/openapi.json), listet jeden Endpunkt mit seinen genauen Anfrage- und Antwortschemas auf.
Authentifizierung
Zwei Methoden, zur Wahl:
API-Schlüssel, empfohlen für ein Skript oder eine Integration eines Drittanbieters (Erstellung und Scopes: API-Schlüssel):
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Session-Cookie (vom Dashboard selbst verwendet):
POST /api/auth/login
Content-Type: application/json
{ "email": "sie@beispiel.com", "password": "..." }
Die Antwort setzt das Cookie sid; es muss bei jedem folgenden Aufruf übermittelt werden (credentials: "include" auf Fetch-Seite). Eine Session wird nicht durch Scopes eingeschränkt, weil sie Ihr angemeldetes Konto darstellt.
Fehler
Jede Fehlerantwort folgt demselben Format:
{ "error": "Lesbare Nachricht", "code": "optionaler_maschinen_code" }
Standard-HTTP-Codes: 400 ungültiger Payload, 401 fehlende/ungültige Authentifizierung, 403 unzureichender Scope oder unzureichende Rolle, 404 Ressource nicht gefunden oder nicht zugänglich (beides wird nicht unterschieden, um nicht die Existenz einer Ressource gegenüber jemandem zu offenbaren, der keinen Zugriff darauf hat), 409 Konflikt, 429 Ratenlimit überschritten.
Ratenlimit
Jeder API-Schlüssel hat sein eigenes Limit (60 Anfragen/Minute standardmäßig, bei Erstellung konfigurierbar bis zu 6000). Jede Antwort trägt die Header:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1732549800
Ein Session-Cookie wird niemals durch diesen Mechanismus limitiert.
Projekte
GET /api/v1/projects Ihre Projekte auflisten (Eigentümer oder Mitglied)
POST /api/v1/projects ein Projekt erstellen
GET /api/v1/projects/:id Details eines Projekts (Dienste, Canvas)
PUT /api/v1/projects/:id umbenennen / Beschreibung ändern
DELETE /api/v1/projects/:id ein Projekt löschen
curl -X POST https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "name": "mein-projekt" }'
Verwaltung von Mitgliedern, Canvas (Positionen/Verbindungen) und Domain-Weiterleitungen auf Projektebene: siehe die interaktive Referenz, noch nicht im generierten Spec abgedeckt.
Dienste
GET /api/v1/services/project/:projectId Dienste eines Projekts
GET /api/v1/services/:id Details eines Dienstes (Live-K8s-Status)
POST /api/v1/services einen Dienst erstellen (GitHub, Upload, Docker, Datenbank)
DELETE /api/v1/services/:id einen Dienst löschen
POST /api/v1/services/:id/redeploy neu deployen
GET /api/v1/services/:id/logs aktuelle Runtime-Logs
GET /api/v1/services/:id/metrics CPU / Speicher momentan
GET /api/v1/services/:id/env Umgebungsvariablen
PUT /api/v1/services/:id/env Variablen ersetzen (startet den Dienst neu)
PUT /api/v1/services/:id/scale Anzahl der Replikate festlegen
GET /api/v1/services/:id/deployments Deployment-Historie
POST /api/v1/services/:id/deployments/:deploymentId/rollback zu einem vorherigen Deployment zurückkehren
curl -X POST https://api.webgune.cloud/api/v1/services/svc_123/redeploy \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Branch-Previews, Datenbank-Exposition, Volumes, benutzerdefinierte Ports, Autoscaling, Discord-Bots: bestehende Endpunkte, noch nicht im generierten OpenAPI-Spec. Siehe Datenbanken, Autoscaling, Deployments & Rollback.
Domains
POST /api/v1/domains/check Verfügbarkeit einer Domain prüfen
GET /api/v1/domains Ihre Domains auflisten
POST /api/v1/domains/register eine verfügbare Domain registrieren
GET /api/v1/domains/:id Details einer Domain
DELETE /api/v1/domains/:id eine Domain löschen
GET /api/v1/domains/:id/dns DNS-Einträge auflisten
POST /api/v1/domains/:id/dns einen DNS-Eintrag hinzufügen
DELETE /api/v1/domains/:id/dns/:idx einen DNS-Eintrag löschen
Nameserver, automatische Verlängerung, manuelle Verlängerung: siehe die interaktive Referenz.
Abrechnung
GET /api/v1/billing/plans verfügbare Pläne auflisten
GET /api/v1/billing/subscription aktives Abonnement (Konto, oder ?projectId= für ein dediziertes Projekt)
GET /api/v1/billing/invoices Ihre Rechnungen auflisten
Abonnement, Zahlung und Webhook bleiben interne Dashboard-Abläufe (Mollie), nicht als API-Operationen für Drittanbieter exponiert.
Dashboard
GET /api/v1/dashboard/stats aggregierte Statistiken (Dienste, CPU/Speicher vs. Plan-Limits)
GET /api/v1/dashboard/deployment-history Deployment-Historie, letzte 30 Tage
API-Schlüssel
GET /api/v1/api-keys Ihre Schlüssel auflisten
POST /api/v1/api-keys einen Schlüssel erstellen
DELETE /api/v1/api-keys/:id einen Schlüssel widerrufen
GET /api/v1/api-keys/:id/audit-log Audit-Protokoll (letzte 100 Anfragen)
Details zu Scopes, Ratenlimit und dem Header X-Act-As-User-Id (Reseller): siehe API-Schlüssel.
Reseller
Vorbehalten Konten, die Eigentümer einer Organisation sind (isOrgOwner):
GET /api/v1/reseller/organization meine Organisation
GET /api/v1/reseller/sub-clients meine Unterkunden auflisten
GET /api/v1/reseller/overview Übersicht (Zähler je Unterkunde)
Erstellung/Löschung von Unterkunden und Reseller-Abrechnung: siehe die interaktive Referenz.
WebSocket: Logs live
const ws = new WebSocket("wss://api.webgune.cloud/ws/services/:id/logs");
ws.onmessage = (e) => console.log(e.data); // eine Log-Zeile pro Nachricht
WebSocket: Metriken live
const ws = new WebSocket("wss://api.webgune.cloud/ws/projects/:id/metrics");
ws.onmessage = (e) => {
const metrics = JSON.parse(e.data);
// { "dienst-id": { cpu: 1.2, memory: 256 }, ... }
};
WebSockets erfordern eine Browser-Session: ein API-Schlüssel kann sich nicht damit verbinden (siehe API-Schlüssel).