API-Referenz
Der Cuby-Server läuft standardmäßig auf Port 3847 und bietet eine REST API sowie Socket.IO-Events für Echtzeit-Kommunikation.
REST API
Health
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/health | Health Check — gibt {status: "ok", timestamp} zurück |
Authentifizierung
| Method | Endpoint | Beschreibung |
|---|---|---|
| POST | /api/auth | Login mit API Key → Session Cookie |
| POST | /api/auth/token | Auth-Token erstellen (60s, einmalig) |
| POST | /api/auth/session | Auth-Token gegen Session Cookie tauschen |
Details unter Authentifizierung.
Konfiguration
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/config | Aktuelle Konfiguration inkl. installierter Produkte, API-Key-Status, Operator-Modus und Version |
| POST | /api/config/apikey | API Key speichern (UUID v4 Format erforderlich) |
| GET | /api/config/autostart | Autostart-Status abfragen |
| POST | /api/config/autostart | Autostart aktivieren/deaktivieren — {enabled: true/false} |
| POST | /api/config/trial | Trial-Lizenz erstellen (generiert UUID, registriert beim Marketplace) |
| GET | /api/config/validate-apikey | API Key gegen Marketplace validieren |
Marketplace
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/marketplace/products | Alle verfügbaren Produkte mit Installationsstatus und Update-Info |
| GET | /api/marketplace/courses | Kurse aus dem Marketplace |
| GET | /api/marketplace/videos | Aktuelle Videos |
Installation
| Method | Endpoint | Beschreibung |
|---|---|---|
| POST | /api/install | Installation starten — Body: {products: [{productId, alias?}]} |
| POST | /api/install/cancel | Ausstehende Installation abbrechen — Body: {instanceId} |
| GET | /api/install/status?productId=X | Installationsfortschritt abfragen |
Beispiel: Produkt installieren
curl -X POST http://localhost:3847/api/install \
-H "Content-Type: application/json" \
-H "Authorization: Bearer DEIN_API_KEY" \
-d '{"products": [{"productId": "processcube-engine"}]}'Beispiel: Produkt mit Alias installieren
curl -X POST http://localhost:3847/api/install \
-H "Content-Type: application/json" \
-H "Authorization: Bearer DEIN_API_KEY" \
-d '{"products": [{"productId": "processcube-engine", "alias": "staging"}]}'Produkte
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/products/status | Status aller laufenden Prozesse |
| GET | /api/products/health | Health-Check aller Produkte |
| POST | /api/products/start-all | Alle konfigurierten Plugins starten |
Einzelnes Produkt
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/products/:id/status | Status eines Produkts |
| GET | /api/products/:id/health | Health-Check eines Produkts |
| POST | /api/products/:id/start | Produkt starten |
| POST | /api/products/:id/stop | Produkt stoppen |
| POST | /api/products/:id/restart | Produkt neustarten |
| GET | /api/products/:id/logs?limit=100 | In-Memory-Logs (Standard: 100 Zeilen) |
| GET | /api/products/:id/logfile?lines=500 | Log-Datei (Standard: 500 Zeilen) |
| POST | /api/products/:id/update | Auf neueste Version aktualisieren |
| DELETE | /api/products/:id/uninstall | Produkt deinstallieren |
Produkt-Konfiguration
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/products/:id/has-config | Prüfen ob Konfigurationsdialog vorhanden |
| GET | /api/products/:id/config | Aktuelle Plugin-Konfiguration |
| POST | /api/products/:id/configure | Konfiguration speichern und Deployment starten |
| GET | /api/products/:id/config-component.js | React-Konfigurationskomponente |
| GET | /api/products/:id/has-detail | Prüfen ob Detail-Komponente vorhanden |
| GET | /api/products/:id/detail-component.js | React-Detail-Komponente |
Plugin-Routes
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET/POST/PUT/DELETE | /api/plugins/:instanceId/* | Weiterleitung an Plugin-registrierte Routes |
ProcessCubes
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/processcubes | Alle registrierten ProcessCube®-Instanzen (lokal + Sub-Cubies) |
Shims
| Method | Endpoint | Beschreibung |
|---|---|---|
| GET | /api/shim/react.js | React-Modul für Plugin-Komponenten |
| GET | /api/shim/react-jsx-runtime.js | JSX-Runtime für Plugin-Komponenten |
| GET | /api/shim/react-dom.js | ReactDOM für Plugin-Komponenten |
Setup
| Method | Endpoint | Beschreibung |
|---|---|---|
| POST | /api/setup/complete | Setup als abgeschlossen markieren |
Installations-Status
| Status | Beschreibung |
|---|---|
installing | Installation läuft |
needs_config | Wartet auf Benutzerkonfiguration |
installed | Erfolgreich installiert |
failed | Installation fehlgeschlagen |
updating | Update läuft |
Produkt-Status
| Status | Beschreibung |
|---|---|
running | Produkt läuft |
stopped | Manuell gestoppt |
crashed | Abgestürzt (Auto-Restart folgt) |
installing | Installation läuft |
installed | Installiert, noch nicht gestartet |
updating | Update läuft |
needs_config | Wartet auf Konfiguration |
failed | Fehlgeschlagen |
Socket.IO Events
Server → Client
| Event | Beschreibung |
|---|---|
install:status | Installationsfortschritt pro Produkt |
products:status | Status-Änderungen aller Produkte |
product:log | Einzelne Log-Zeilen eines Produkts |
system:status | System-Setup-Fortschritt (Node.js-Installation etc.) |
processcube:registered | Neue ProcessCube®-Instanz registriert |
processcube:unregistered | ProcessCube®-Instanz entfernt |
Client → Server
| Event | Beschreibung |
|---|---|
subscribe:logs | Log-Stream für ein Produkt abonnieren — {productId} |
unsubscribe:logs | Log-Stream abbestellen — {productId} |
Plugin Socket.IO Namespaces
Plugins können eigene Events über dedizierte Namespaces registrieren:
- Namespace-Pfad:
/plugins/<instanceId>(URL-encoded) - Auth: Socket.IO-Auth-Middleware wird automatisch angewandt
- Cleanup: Namespace wird bei Stop/Crash automatisch entfernt
Details unter Plugin-System.
Verbindungsbeispiel
REST API mit curl
# Health Check
curl http://localhost:3847/api/health
# Config abfragen (mit Auth)
curl -H "Authorization: Bearer DEIN_API_KEY" http://localhost:3847/api/config
# Produkt starten
curl -X POST -H "Authorization: Bearer DEIN_API_KEY" \
http://localhost:3847/api/products/processcube-engine/start
# Logs abrufen
curl -H "Authorization: Bearer DEIN_API_KEY" \
http://localhost:3847/api/products/processcube-engine/logs?limit=50Socket.IO mit JavaScript
import { io } from 'socket.io-client';
const socket = io('http://localhost:3847', {
auth: { apiKey: 'DEIN_API_KEY' }
});
// Status-Updates empfangen
socket.on('products:status', (statuses) => {
console.log('Produkt-Status:', statuses);
});
// Install-Fortschritt empfangen
socket.on('install:status', ({ productId, progress, message }) => {
console.log(`[${productId}] ${progress}% — ${message}`);
});
// Logs abonnieren
socket.emit('subscribe:logs', { productId: 'processcube-engine' });
socket.on('product:log', ({ productId, line }) => {
console.log(`[${productId}] ${line}`);
});