HTTP-API

Die HTTP-API ist die Integrationsschnittstelle für Beam Bench. Die Desktop-App, die CLI und alle externen Clients kommunizieren mit denselben Routen. Wenn Sie Beam Bench in einer Umgebung ohne CLI benötigen (Web-App, Integrationsserver, mobile App oder eigene Werkzeuge), verwenden Sie die API direkt.

Die API ist in der Desktop-App enthalten und wird prozessintern ausgeführt. Es muss kein separater Dienst installiert werden.

Standardeinstellungen und Sicherheit

In der aktuellen Version wird der lokale API-Server mit folgenden Einstellungen ausgeliefert:

• Lokale API: aus.
• API-Port: 5900.
• Netzwerkgeräte zulassen: aus. Wenn die API aktiviert ist, bindet sie sich an 127.0.0.1 und akzeptiert nur Verbindungen von diesem Computer.

Die API nimmt erst Verbindungen an, nachdem Sie sie ausdrücklich aktiviert haben. Der Netzwerkzugriff muss separat aktiviert werden, da die API keine Authentifizierung verwendet und Vorgänge ermöglicht, die die Maschine bewegen und den Laser auslösen können.

Ändern Sie zur Verwendung der API deren Einstellungen unter Einstellungen → Allgemein:

1. Öffnen Sie die Desktop-App.
2. Bearbeiten → Einstellungen → Allgemein.
3. Schalten Sie Lokale API ein.
4. Lassen Sie Netzwerkgeräte zulassen ausgeschaltet, sofern nicht ein anderes vertrauenswürdiges Gerät eine Verbindung herstellen muss.

Änderungen werden sofort wirksam; ein Neustart ist nicht erforderlich.

Basis-URL

http://<host>:5900/api/v1

<host> ist localhost (oder 127.0.0.1), wenn Netzwerkgeräte zulassen ausgeschaltet ist. Ist die Einstellung eingeschaltet, ist der Server von jedem Gerät im Netzwerk über die LAN-IP-Adresse der Maschine erreichbar.

Der Port kann unter Einstellungen → Allgemein konfiguriert werden; der Standardwert ist 5900.

Authentifizierung

Keine. Die API verwendet weder Token noch Schlüssel oder Anmeldung.

• Bei einer Bindung an localhost bildet das Zugriffsmodell des Betriebssystems die Sicherheitsgrenze: Jeder Prozess auf Ihrem Computer kann mit der API kommunizieren.
• Bei aktivierter Netzwerkbindung kann jeder im selben Netzwerk mit der API kommunizieren. Verwenden Sie den Netzwerkbindungsmodus nicht in einem nicht vertrauenswürdigen WLAN.

Anfrageformat

Alle POST/PATCH/PUT-Anfragetexte sind JSON:

Content-Type: application/json

Abfragezeichenfolgen bestehen aus einfachen key=value-Paaren. Pfadsegmente werden wie üblich URL-codiert.

Antwortstruktur

Bei erfolgreichen Antworten wird der Ressourcentext direkt und ohne umschließende Struktur zurückgegeben:

{
  "field": "value",
  "...": "..."
}

Fehler werden in einer einheitlichen Struktur zurückgegeben:

{
  "error": {
    "code": "InvalidInput",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code hat einen der folgenden Werte:

Bestätigungspflichtige Fehler

Einige wenige Vorgänge können die Maschine bewegen oder den Laser auslösen. Diese Endpunkte erfordern im Anfragetext ein ausdrückliches Bestätigungsflag. Fehlt dieses, gibt die API 428 Precondition Required zurück:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

Senden Sie die Anfrage erneut und setzen Sie das genannte Flag auf true. Derzeit werden die Flags confirm_motion, confirm_laser_on, confirm_raw_gcode und confirm_air_assist verwendet.

Endpunktgruppen

Die Referenzseiten für die einzelnen Ressourcen befinden sich noch in Arbeit; konsultieren Sie bis dahin das Funktionsschema des Agenten.

Verfügbare Schnittstelle ermitteln

Am schnellsten können Sie wie folgt feststellen, welche Funktionen Ihre installierte Version bereitstellt:

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Dadurch wird das vollständige Funktionsschema einschließlich aller Endpunkte, ihrer Parameter und ihrer Antwortstruktur zurückgegeben. Das Schema ist die maßgebliche Beschreibung; diese Seite dient als Leitfaden dazu.

Zur Zustandsabfrage:

curl -s http://localhost:5900/api/v1/agent/state | jq .

Für eine schriftliche Einführung in die Steuerung der App:

curl -s http://localhost:5900/api/v1/agent/guide

Versionierung

Alle Routen befinden sich unter /api/v1. Inkompatible Änderungen werden gegebenenfalls unter /api/v2 eingeführt. Erweiterungen (neue Endpunkte, neue optionale Felder) werden ohne Erhöhung der Versionsnummer in v1 veröffentlicht.

Verwandte Themen

• Anleitung zur Verwendung der HTTP-API: eine Einführung im Tutorial-Stil mit ausgearbeiteten Beispielen.
• Wie CLI und App ihren Zustand gemeinsam verwenden: das Konsistenzmodell hinter diesen Endpunkten.
• Einstellungen → Allgemein: Hier können Sie die API aktivieren und den Port auswählen.