HTTP API

De HTTP API is het integratieoppervlak voor Beam Bench. De meeste CLI-opdrachten en externe clients gebruiken deze routes. De desktopfrontend roept de gedeelde service aan via Tauri IPC en heeft de HTTP-server bij normaal gebruik niet nodig. Als je Beam Bench wilt gebruiken in een omgeving zonder CLI, zoals een 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 de server alleen verbindingen vanaf deze computer.

De API luistert pas naar verbindingen nadat je dit hebt ingeschakeld. Netwerktoegang inschakelen is een afzonderlijke opt-in, omdat de API geen authenticatie gebruikt en bewerkingen bevat waarmee je de machine kunt bewegen en de laser kunt inschakelen.

Als je de API wilt gebruiken, wijzig je de instellingen via Instellingen → Algemeen:

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 toegepast; opnieuw opstarten is niet nodig.

Basis-URL

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

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

De poort kan worden geconfigureerd via Instellingen → Algemeen; 5900 is de standaardwaarde.

Authenticatie

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

• Bij binding aan localhost vormt het toegangsmodel op besturingssysteemniveau de grens: elk proces op je machine kan met de API communiceren.
• Als netwerkbinding is ingeschakeld, kan iedereen op hetzelfde netwerk met de API communiceren. Gebruik de modus met netwerkbinding niet op niet-vertrouwde wifi.

Aanvraagindeling

Alle POST/PATCH/PUT-hoofdinvoeren zijn JSON:

Content-Type: application/json

Querystrings zijn vlakke key=value-paren. Padsegmenten worden zoals gebruikelijk URL-gecodeerd.

Antwoordomhulsel

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

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

Fouten retourneren een uniform omhulsel:

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

error.code is een van de volgende waarden:

Fouten waarvoor bevestiging nodig is

Een kleine groep bewerkingen kan de machine bewegen of de laser inschakelen. Voor deze eindpunten is een expliciete bevestigingsvlag vereist 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."
}

Stuur de aanvraag opnieuw met de genoemde vlag ingesteld op true. De vlaggen die momenteel worden gebruikt zijn confirm_motion, confirm_laser_on, confirm_raw_gcode en confirm_air_assist.

Gelijktijdige projectbewerkingen

Ontwerptransacties vergelijken het vastgelegde project op het moment van vastleggen. Een gelijktijdige bewerking, projectwissel of sluiting kan stale_revision retourneren. Vernieuw de status en beoordeel de wijziging opnieuw voordat je het opnieuw probeert. Speel niet blindelings een oudere projectsnapshot af over nieuwer werk.

Groepen met eindpunten

Referentiepagina's per resource zijn nog in ontwikkeling. Raadpleeg intussen het schema voor agentmogelijkheden.

Het actieve oppervlak ontdekken

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

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

Dit retourneert het volledige schema met mogelijkheden, waaronder elk eindpunt, de parameters en de antwoordstructuur. Het schema is de gezaghebbende beschrijving; deze pagina is een gids daarbij.

Voor statusinzage:

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. Bij niet-compatibele wijzigingen wordt /api/v2 gebruikt. Aanvullende wijzigingen, zoals nieuwe eindpunten en nieuwe optionele velden, worden in v1 geleverd zonder versienummerverhoging.

Gerelateerd

• De HTTP API gebruiken: een inleiding in tutorialstijl met uitgewerkte voorbeelden.
• Hoe de CLI en app status delen: het consistentiemodel achter deze eindpunten.
• Instellingen → Algemeen: waar je de API inschakelt en de poort kiest.