HTTP-API

HTTP-API-et er integrasjonsgrensesnittet for Beam Bench. De fleste CLI-kommandoer og eksterne klienter bruker disse rutene. Skrivebordsfrontend-en kaller den delte tjenesten gjennom Tauri IPC og trenger ikke HTTP-serveren ved normal bruk. Hvis du har et bruksområde som trenger Beam Bench i et miljø uten CLI, for eksempel en webapp, integrasjonsserver, mobilapp eller egne verktøy, kan du bruke API-et direkte.

API-et leveres med skrivebordsappen og kjører i samme prosess. Det finnes ingen separat tjeneste som må installeres.

Standardverdier og sikkerhet

I den gjeldende versjonen leveres den lokale API-serveren med disse innstillingene:

• Lokalt API: av.
• API-port: 5900.
• Tillat at enheter i nettverket kobler til: av. Når API-et er aktivert, bindes det til 127.0.0.1 og godtar bare tilkoblinger fra denne datamaskinen.

API-et lytter ikke etter tilkoblinger før du aktivt velger det. Nettverkstilgang krever et separat aktivt valg fordi API-et ikke har autentisering og inneholder operasjoner som kan flytte maskinen og aktivere laseren.

For å bruke API-et endrer du innstillingene under Innstillinger → Generelt:

1. Åpne skrivebordsappen.
2. Rediger → Innstillinger → Generelt.
3. Slå på Lokalt API.
4. La Tillat at enheter i nettverket kobler til være av med mindre en annen klarert enhet må koble til.

Endringene gjelder umiddelbart. Omstart er ikke nødvendig.

Basisadresse

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

<host> er localhost (eller 127.0.0.1) når Tillat at enheter i nettverket kobler til er av. Når den er på, er serveren tilgjengelig på maskinens LAN-IP fra alle enheter i nettverket.

Porten kan konfigureres under Innstillinger → Generelt. 5900 er standardverdien.

Autentisering

Ingen. API-et har ingen token, nøkkel eller innlogging.

• Med localhost-binding er tilgangsmodellen på operativsystemnivå grensen: enhver prosess på maskinen kan snakke med API-et.
• Når nettverksbinding er aktivert, kan alle på samme nettverk snakke med API-et. Ikke bruk nettverksbindingsmodus på et uklarert Wi-Fi-nettverk.

Forespørselsformat

Alle POST/PATCH/PUT-organer er JSON:

Content-Type: application/json

Spørringsstrenger er flate key=value. Banelementer URL-kodes som vanlig.

Svarinnpakning

Vellykkede svar returnerer ressursens innhold direkte, uten innpakning:

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

Feil returnerer en ensartet innpakning:

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

error.code er én av disse:

Feil som krever bekreftelse

Et lite antall operasjoner kan flytte maskinen eller aktivere laseren. Disse endepunktene krever et uttrykkelig bekreftelsesflagg i forespørselsorganet. Hvis det 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 forespørselen på nytt med det navngitte flagget satt til true. Flaggene som brukes nå, er confirm_motion, confirm_laser_on, confirm_raw_gcode og confirm_air_assist.

Samtidige prosjektendringer

Designtransaksjoner sammenligner prosjektet de tok et øyeblikksbilde av, når endringene bekreftes. En samtidig endring, et prosjektskifte eller en lukking kan returnere stale_revision. Oppdater tilstanden og vurder endringen på nytt før du prøver igjen. Ikke spill blindt av et eldre prosjektøyeblikksbilde over nyere arbeid.

Endepunktgrupper

Referansesider for hver ressurs er under utvikling. Se kapabilitetsskjemaet for agenten i mellomtiden.

Finn det aktive grensesnittet

Den raskeste måten å se hva den installerte versjonen din tilbyr på:

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

Dette returnerer hele kapabilitetsskjemaet, inkludert alle endepunkter, parameterne deres og formen på svarene. Skjemaet er den autoritative beskrivelsen. Denne siden er en veiledning til det.

For introspeksjon av tilstanden:

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

For en skriftlig innføring i hvordan du styrer appen:

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

Versjonering

Alle ruter ligger under /api/v1. Brytende endringer legges i /api/v2 når de oppstår. Tilleggsendringer, som nye endepunkter og nye valgfrie felt, leveres i v1 uten at versjonen økes.

Relatert

• Veiledning for bruk av HTTP-API-et: en innføring i veiledningsform med gjennomarbeidede eksempler.
• Slik deler CLI og app tilstand: konsistensmodellen bak disse endepunktene.
• Innstillinger → Generelt: her aktiverer du API-et og velger port.