HTTP-API

De HTTP-API is het integratieoppervlak voor Beam Bench. De desktopapp, de CLI en elke externe client communiceren met dezelfde routes. Als je Beam Bench wilt gebruiken in een omgeving zonder CLI (webapp, integratieserver, mobiele app of eigen tooling), gebruik je de API rechtstreeks.

De API wordt meegeleverd met de desktopapp en draait in-process. Je hoeft geen afzonderlijke service te installeren.

Standaardwaarden en beveiliging

In de huidige build wordt de lokale API-server geleverd met deze instellingen:

• Lokale API: uit.
• API-poort: 5900.
• Netwerkapparaten toestaan: uit. Wanneer de API is ingeschakeld, bindt deze aan 127.0.0.1 en accepteert deze alleen verbindingen vanaf deze computer.

De API luistert pas naar verbindingen nadat je deze hebt ingeschakeld. Netwerktoegang inschakelen vereist een afzonderlijke bevestiging, omdat de API geen authenticatie gebruikt en bewerkingen bevat die de machine kunnen bewegen en de laser kunnen activeren.

Wijzig de instellingen vanuit Instellingen → Algemeen om de API te gebruiken:

1. Open de desktopapp.
2. Bewerken → Instellingen → Algemeen.
3. Schakel Lokale API in.
4. Laat Netwerkapparaten toestaan uit, tenzij een ander vertrouwd apparaat verbinding moet maken.

Wijzigingen worden onmiddellijk actief; opnieuw opstarten is niet nodig.

Basis-URL

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

<host> is localhost (of 127.0.0.1) wanneer Netwerkapparaten toestaan uit staat. Wanneer deze optie aan staat, is de server vanaf elk apparaat op het netwerk bereikbaar via het LAN-IP-adres van de machine.

Je kunt de poort configureren via Instellingen → Algemeen; 5900 is de standaardwaarde.

Authenticatie

Geen. De API heeft geen token, sleutel of aanmelding.

• Bij een localhost-binding vormt het toegangsmodel op besturingssysteemniveau de grens: elk proces op je machine kan met de API communiceren.
• Bij ingeschakelde netwerkbinding kan iedereen op hetzelfde netwerk met de API communiceren. Gebruik de netwerkbindingsmodus niet op niet-vertrouwde wifi.

Aanvraagindeling

Alle POST/PATCH/PUT-inhoud is JSON:

Content-Type: application/json

Querytekenreeksen zijn platte key=value. Padsegmenten worden zoals gebruikelijk gecodeerd voor URL's.

Antwoordomhulling

Geslaagde antwoorden retourneren de resource-inhoud rechtstreeks, zonder omhulling:

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

Fouten retourneren een uniforme omhulling:

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

error.code is een van de volgende waarden:

Fouten waarvoor bevestiging vereist is

Een klein aantal bewerkingen kan de machine bewegen of de laser activeren. Deze endpoints vereisen een expliciete bevestigingsvlag in de aanvraaginhoud. Als die ontbreekt, retourneert de API 428 Precondition Required:

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

Verstuur de aanvraag opnieuw met de genoemde vlag ingesteld op true. De momenteel gebruikte vlaggen zijn confirm_motion, confirm_laser_on, confirm_raw_gcode en confirm_air_assist.

Endpointgroepen

Referentiepagina's per resource zijn nog in ontwikkeling; raadpleeg voorlopig het schema met agentmogelijkheden.

Het actieve oppervlak ontdekken

De snelste manier om te zien wat je geïnstalleerde versie beschikbaar stelt:

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

Dit retourneert het volledige schema met mogelijkheden, inclusief elk endpoint, de parameters ervan en de antwoordvorm. Het schema is de gezaghebbende beschrijving; deze pagina is een handleiding daarbij.

Voor statusinspectie:

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

Voor een schriftelijke uitleg over het bedienen van de app:

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

Versiebeheer

Alle routes vallen onder /api/v1. Wanneer er breaking changes optreden, komen deze in /api/v2. Aanvullende wijzigingen (nieuwe endpoints en nieuwe optionele velden) worden in v1 uitgebracht zonder verhoging van het versienummer.

Gerelateerd

• Handleiding voor het gebruik van de HTTP-API: een introductie in tutorialstijl met uitgewerkte voorbeelden.
• Hoe de CLI en de app status delen: het consistentiemodel achter deze endpoints.
• Instellingen → Algemeen: waar je de API inschakelt en de poort kiest.