HTTP API

Die HTTP API ist die Integrationsschnittstelle für Beam Bench. Die meisten CLI-Befehle und externen Clients verwenden diese Routen. Das Desktop-Frontend ruft den gemeinsamen Dienst über Tauri IPC auf und benötigt den HTTP-Server für die normale Nutzung nicht. Wenn Sie Beam Bench in einer Umgebung ohne CLI verwenden möchten, etwa in einer Web-App, einem Integrationsserver, einer mobilen App oder Ihren eigenen Werkzeugen, verwenden Sie die API direkt.

Die API wird mit der Desktop-App ausgeliefert und läuft im Prozess. Es muss kein separater Dienst installiert werden.

Standardeinstellungen und Sicherheit

In der aktuellen Version wird der lokale API-Server mit diesen 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, wenn Sie sie ausdrücklich aktivieren. Der Netzwerkzugriff erfordert eine separate ausdrückliche Aktivierung, da die API keine Authentifizierung verwendet und Vorgänge umfasst, die die Maschine bewegen und den Laser auslösen können.

Um die API zu verwenden, ändern Sie ihre 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, außer ein anderes vertrauenswürdiges Gerät muss eine Verbindung herstellen.

Ä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. Wenn die Option eingeschaltet ist, ist der Server unter der LAN-IP der Maschine von jedem Gerät im Netzwerk erreichbar.

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

Authentifizierung

Keine. Die API hat kein Token, keinen Schlüssel und keine Anmeldung.

• Bei einer Localhost-Bindung bildet das Zugriffssystem des Betriebssystems die Grenze: Jeder Prozess auf Ihrer Maschine kann mit der API kommunizieren.
• Bei aktivierter Netzwerkbindung kann jeder im selben Netzwerk mit der API kommunizieren. Verwenden Sie den Netzwerkbindungsmodus nicht in nicht vertrauenswürdigen WLANs.

Anfrageformat

Alle POST/PATCH/PUT-Bodys sind JSON:

Content-Type: application/json

Abfragezeichenfolgen bestehen aus flachen key=value-Paaren. Pfadsegmente werden wie üblich URL-kodiert.

Antwortstruktur

Erfolgreiche Antworten geben den Ressourcen-Body direkt und ohne Wrapper zurück:

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

Fehler geben eine einheitliche Struktur zurück:

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

error.code ist einer der folgenden Werte:

Fehler mit erforderlicher Bestätigung

Eine kleine Anzahl von Vorgängen kann die Maschine bewegen oder den Laser auslösen. Diese Endpunkte erfordern ein ausdrückliches Bestätigungsflag im Anfrage-Body. Fehlt es, 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, wobei das genannte Flag auf true gesetzt ist. Die derzeit verwendeten Flags sind confirm_motion, confirm_laser_on, confirm_raw_gcode und confirm_air_assist.

Gleichzeitige Projektänderungen

Designtransaktionen vergleichen ihr erfasstes Projekt zum Zeitpunkt des Commits. Eine gleichzeitige Änderung, ein Projektwechsel oder ein Schließen kann stale_revision zurückgeben. Aktualisieren Sie den Zustand und bewerten Sie die Änderung erneut, bevor Sie es noch einmal versuchen. Spielen Sie einen älteren Projektsnapshot nicht blind über neuere Arbeit.

Endpunktgruppen

Referenzseiten für einzelne Ressourcen sind noch in Arbeit. Sehen Sie bis dahin im Schema der Agentenfunktionen nach.

Die aktuelle Schnittstelle ermitteln

So sehen Sie am schnellsten, was Ihre installierte Version bereitstellt:

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

Dies gibt das vollständige Schema der Funktionen zurück, einschließlich jedes Endpunkts, seiner Parameter und seiner Antwortstruktur. Das Schema ist die maßgebliche Beschreibung. Diese Seite dient als Orientierung dazu.

Für die Zustandsermittlung:

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

Für eine schriftliche Orientierung zur Steuerung der App:

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

Versionierung

Alle Routen befinden sich unter /api/v1. Bei einschneidenden Änderungen wird /api/v2 verwendet. Ergänzende Änderungen, etwa neue Endpunkte oder neue optionale Felder, werden in v1 ohne Erhöhung der Version ausgeliefert.

Verwandte Themen

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