HTTP API

HTTP-API-et er integrasjonsgrensesnittet for Beam Bench. Skrivebordsappen, CLI-en og alle eksterne klienter bruker de samme rutene. Hvis du har et bruksområde som trenger Beam Bench i et miljø uten CLI, for eksempel en nettapp, integrasjonsserver, mobilapp eller egne verktøy, bruker du API-et direkte.

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

Standardinnstillinger og sikkerhet

I den nåværende 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 velger å aktivere det. Nettverkstilgang krever et separat aktivt valg fordi API-et ikke har autentisering og inneholder operasjoner som kan flytte maskinen og utløse laseren.

Hvis du vil 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 trer i kraft umiddelbart. Du trenger ikke å starte appen på nytt.

Basis-URL

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å, kan serveren nås på maskinens lokale IP-adresse 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.

• Ved binding til localhost er tilgangsmodellen på operativsystemnivå grensen: Alle prosesser på maskinen kan kommunisere med API-et.
• Når nettverksbinding er aktivert, kan alle på samme nettverk kommunisere med API-et. Ikke bruk nettverksbindingsmodus på usikret Wi-Fi.

Forespørselsformat

Alle POST/PATCH/PUT-kropper er JSON:

Content-Type: application/json

Spørringsstrenger er flate key=value. Banelementer URL-kodes på vanlig måte.

Svarinnpakning

Vellykkede svar returnerer ressursens innhold direkte, uten innpakking:

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

Feil returnerer en enhetlig innpakking:

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

error.code er én av:

Feil som krever bekreftelse

Et lite antall operasjoner kan flytte maskinen eller utløse laseren. Disse endepunktene krever et uttrykkelig bekreftelsesflagg i forespørselsinnholdet. Hvis flagget 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 for øyeblikket brukes, er confirm_motion, confirm_laser_on, confirm_raw_gcode og confirm_air_assist.

Grupper av endepunkter

Referansesider for de enkelte ressursene er under utvikling. Se agentens funksjonsskjema i mellomtiden.

Finn det aktive grensesnittet

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

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

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

For å undersøke 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 det blir aktuelt. Tilleggsendringer, som nye endepunkter og nye valgfrie felt, leveres i v1 uten at versjonen økes.

Relatert

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