HTTP API

API HTTP je integracijski vmesnik za Beam Bench. Večina ukazov CLI in zunanji odjemalci uporablja te poti. Namizni vmesnik kliče skupno storitev prek Tauri IPC in za običajno uporabo ne potrebuje strežnika HTTP. Če želite Beam Bench uporabljati v okolju, ki ni CLI, na primer v spletni aplikaciji, integracijskem strežniku, mobilni aplikaciji ali lastnem orodju, uporabite API neposredno.

API je priložen namizni aplikaciji in se izvaja znotraj procesa. Ločene storitve ni treba namestiti.

Privzete nastavitve in varnost

V trenutni gradnji so lokalne nastavitve API-ja naslednje:

• Lokalni API: izklopljen.
• Vrata API: 5900.
• Dovolite omrežnim napravam povezavo: izklopljeno. Ko je API omogočen, se poveže z 127.0.0.1 in sprejema povezave samo iz tega računalnika.

API ne posluša povezav, dokler ga izrecno ne omogočite. Omogočanje omrežnega dostopa je ločena izrecna možnost, ker API nima preverjanja pristnosti in vključuje operacije, ki lahko premaknejo napravo in sprožijo laser.

Če želite uporabljati API, spremenite njegove nastavitve v Nastavitve → Splošno:

1. Odprite namizno aplikacijo.
2. Uredi → Nastavitve → Splošno.
3. Vklopite Lokalni API.
4. Dovolite omrežnim napravam povezavo pustite izklopljeno, razen če se mora povezati druga zaupanja vredna naprava.

Spremembe začnejo veljati takoj, ponovni zagon ni potreben.

Osnovni URL

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

<host> je localhost oziroma 127.0.0.1, ko je možnost Dovolite omrežnim napravam povezavo izklopljena. Ko je vklopljena, je strežnik iz katere koli naprave v omrežju dosegljiv prek naslova LAN IP tega računalnika.

Vrata lahko nastavite v Nastavitve → Splošno, privzeta vrednost je 5900.

Preverjanje pristnosti

Brez preverjanja pristnosti. API nima žetona, ključa ali prijave.

• Pri povezavi z localhostom je meja model dostopa na ravni operacijskega sistema, zato lahko z API-jem komunicira vsak proces v vašem računalniku.
• Pri omogočeni omrežni povezavi lahko z API-jem komunicira kdor koli v istem omrežju. Na nezaupanja vrednem omrežju Wi-Fi ne uporabljajte načina z omrežno povezavo.

Oblika zahtev

Vsa telesa zahtev POST/PATCH/PUT so JSON:

Content-Type: application/json

Poizvedbeni nizi so ravni pari ključ=vrednost. Odseki poti so kodirani kot URL po običajnih pravilih.

Ovojnica odgovora

Uspešni odgovori vrnejo telo vira neposredno, brez ovojnice:

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

Napake vrnejo enotno ovojnico:

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

error.code je ena od teh vrednosti:

Napake, ki zahtevajo potrditev

Majhen nabor operacij lahko premakne napravo ali sproži laser. Te končne točke zahtevajo izrecno zastavico za potrditev v telesu zahteve. Če manjka, API vrne 428 Precondition Required:

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

Zahtevo pošljite znova z imenovano zastavico, nastavljeno na true. Trenutno se uporabljajo zastavice confirm_motion, confirm_laser_on, confirm_raw_gcode in confirm_air_assist.

Sočasno urejanje projektov

Transakcije oblikovanja primerjajo zajeti projekt ob potrditvi. Sočasno urejanje, preklop projekta ali zapiranje lahko vrne stale_revision. Osvežite stanje in pred ponovnim poskusom znova ocenite spremembo. Starega posnetka projekta ne predvajajte slepo čez novejše delo.

Skupine končnih točk

Referenčne strani za posamezne vire so še v pripravi, zato si medtem oglejte shemo zmožnosti agenta.

Odkrijte dejanski vmesnik

Najhitreje preverite, kaj omogoča nameščena različica:

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

To vrne celotno shemo zmožnosti, vključno z vsako končno točko, njenimi parametri in obliko odgovora. Shema je merodajen opis, ta stran pa je njen vodnik.

Za vpogled v stanje:

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

Za pisna navodila o upravljanju aplikacije:

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

Različice

Vse poti so pod /api/v1. Prelomne spremembe bodo uvedene v /api/v2, ko se pojavijo. Dopolnilne spremembe, na primer nove končne točke in nova neobvezna polja, so izdane v v1 brez spremembe različice.

Povezano

• Vodnik za uporabo API-ja HTTP: uvod v obliki vadnice s praktičnimi primeri.
• Kako si CLI in aplikacija delita stanje: model doslednosti za temi končnimi točkami.
• Nastavitve → Splošno: mesto, kjer omogočite API in izberete vrata.