HTTP-API

HTTP-API'et er integrationsgrænsefladen til Beam Bench. De fleste CLI-kommandoer og eksterne klienter bruger disse ruter. Desktopfrontend'en kalder den delte tjeneste gennem Tauri IPC og kræver ikke HTTP-serveren ved normal brug. Hvis du har et behov, der kræver Beam Bench i et miljø uden CLI, for eksempel en webapp, integrationsserver, mobilapp eller dine egne værktøjer, skal du bruge API'et direkte.

API'et leveres 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: fra.
• API-port: 5900.
• Tillad netværksenheder: fra. Når API'et er aktiveret, bindes det 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 funktioner, der kan flytte maskinen og aktivere laseren.

For at 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 slået fra, medmindre en anden godkendt enhed skal oprette forbindelse.

Ændringer 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 slået fra. Når den er slået til, kan serveren nås på maskinens LAN-IP fra enhver enhed på netværket.

Porten kan konfigureres i Indstillinger → Generelt, 5900 er standarden.

Godkendelse

Ingen. API'et har hverken token, nøgle eller login.

• Ved localhost-binding er adgangsmodellen på operativsystemniveau grænsen: Alle processer på din maskine kan tale med API'et.
• Når netværksbinding er aktiveret, kan alle på det samme netværk tale med API'et. Brug ikke netværksbinding på et Wi-Fi-netværk, du ikke har tillid til.

Forespørgselsformat

Alle POST/PATCH/PUT-forespørgsler har JSON som brødtekst:

Content-Type: application/json

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

Svarstruktur

Vellykkede svar returnerer ressourcebrødteksten direkte uden indpakning:

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

Fejl returnerer en ensartet struktur:

{
  "error": {
    "code": "invalid_input",
    "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 slutpunkter kræver et eksplicit bekræftelsesflag i forespørgselsbrødteksten. 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ørgslen igen med det navngivne flag sat til true. De flag, der aktuelt bruges, er confirm_motion, confirm_laser_on, confirm_raw_gcode og confirm_air_assist.

Samtidige projektredigeringer

Designtransaktioner sammenligner det registrerede projekt på committidspunktet. En samtidig redigering, et projektskift eller en lukning kan returnere stale_revision. Opdater tilstanden, og vurder ændringen igen, før du prøver igen. Afspil ikke blindt et ældre projektøjebliksbillede oven på nyere arbejde.

Slutpunktgrupper

Referencer til de enkelte ressourcer er stadig under udarbejdelse. Se agentens funktionsskema imens.

Find den aktive grænseflade

Den hurtigste måde at se, hvad din installerede version viser:

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

Dette returnerer hele funktionsskemaet, inklusive alle slutpunkter, deres parametre og deres svarstruktur. Skemaet er den autoritative beskrivelse, denne side er en vejledning til det.

For at se tilstanden:

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

For en skriftlig introduktion til, hvordan appen betjenes:

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

Versionsstyring

Alle ruter ligger under /api/v1. Brydende ændringer kommer i /api/v2, når de forekommer. Tilføjelser, som nye slutpunkter og nye valgfrie felter, leveres i v1 uden ændring af versionen.

Relateret

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