HTTP API

HTTP-API'et er integrationsgrænsefladen til Beam Bench. Desktopappen, CLI'en og alle eksterne klienter kommunikerer med de samme ruter. Hvis du har et anvendelsesområde, der kræver Beam Bench i et miljø uden CLI (webapp, integrationsserver, mobilapp, dine egne værktøjer), skal du bruge API'et direkte.

API'et leveres sammen med desktopappen og kører i processen. Der er ingen separat tjeneste, der skal installeres.

Standardindstillinger og sikkerhed

I den aktuelle version leveres den lokale API-server med disse indstillinger:

• Lokal API: deaktiveret.
• API-port: 5900.
• Tillad netværksenheder: deaktiveret. Når API'et er aktiveret, binder det sig til 127.0.0.1 og accepterer kun forbindelser fra denne computer.

API'et lytter ikke efter forbindelser, før du aktivt vælger det. Aktivering af netværksadgang kræver et separat aktivt valg, fordi API'et ikke har godkendelse og indeholder handlinger, der kan flytte maskinen og aktivere laseren.

Hvis du vil bruge API'et, skal du ændre indstillingerne fra Indstillinger → Generelt:

1. Åbn desktopappen.
2. Rediger → Indstillinger → Generelt.
3. Slå Lokal API til.
4. Lad Tillad netværksenheder være deaktiveret, medmindre en anden betroet enhed skal oprette forbindelse.

Ændringerne træder i kraft med det samme, der kræves ingen genstart.

Basis-URL

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

<host> er localhost (eller 127.0.0.1), når Tillad netværksenheder er deaktiveret. Når den er aktiveret, kan serveren nås på maskinens LAN-IP fra enhver enhed på netværket.

Porten kan konfigureres under Indstillinger → Generelt, 5900 er standardindstillingen.

Godkendelse

Ingen. API'et har intet token, ingen nøgle og intet login.

• Ved binding til localhost er adgangen på operativsystemniveau grænsen: Alle processer på din computer kan kommunikere med API'et.
• Når netværksbinding er aktiveret, kan alle på det samme netværk kommunikere med API'et. Brug ikke netværksbinding på et netværk med ikke-betroet Wi-Fi.

Anmodningsformat

Alle POST/PATCH/PUT-legemer er JSON:

Content-Type: application/json

Forespørgselsstrenge er flade key=value. Stisegmenter URL-kodes som normalt.

Svarindpakning

Vellykkede svar returnerer ressourcelegemet direkte uden indpakning:

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

Fejl returnerer en ensartet indpakning:

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

error.code er en af følgende:

Fejl, der kræver bekræftelse

En mindre gruppe handlinger kan flytte maskinen eller aktivere laseren. Disse endepunkter kræver et eksplicit bekræftelsesflag i anmodningslegemet. Hvis flaget mangler, returnerer API'et 428 Precondition Required:

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

Send anmodningen igen med det angivne flag sat til true. De flag, der aktuelt bruges, er confirm_motion, confirm_laser_on, confirm_raw_gcode og confirm_air_assist.

Endepunktgrupper

Referencessider for de enkelte ressourcer er under udarbejdelse. Se i mellemtiden skemaet for agentfunktioner.

Se den aktuelle grænseflade

Den hurtigste måde at se, hvad din installerede version stiller til rådighed, er:

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

Dette returnerer hele skemaet for funktionerne, herunder alle endepunkter, deres parametre og formen på deres svar. Skemaet er den autoritative beskrivelse, denne side er en vejledning til det.

Hvis du vil se tilstanden:

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

Hvis du vil have en skriftlig introduktion til, hvordan appen styres:

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

Versionering

Alle ruter ligger under /api/v1. Breaking changes placeres i /api/v2, når de opstår. Tilføjelser (nye endepunkter og nye valgfrie felter) leveres i v1 uden ændring af versionsnummeret.

Relateret

• Vejledning til brug af HTTP-API'et: en introduktion i tutorialform med gennemarbejdede eksempler.
• Sådan deler CLI'en og appen tilstand: konsistensmodellen bag disse endepunkter.
• Indstillinger → Generelt: her aktiverer du API'et og vælger porten.