HTTP API

HTTP API je integracijski vmesnik za Beam Bench. Namizna aplikacija, CLI in vsi zunanji odjemalci uporabljajo iste poti. Če potrebujete Beam Bench v okolju, ki ni CLI, na primer v spletni aplikaciji, integracijskem strežniku, mobilni aplikaciji ali lastnem orodju, uporabite API neposredno.

API je vključen v namizno aplikacijo in deluje v istem procesu. Ločene storitve ni treba namestiti.

Privzete nastavitve in varnost

V trenutni različici lokalni strežnik API uporablja te nastavitve:

• Lokalni API: izklopljeno.
• Vrata API: 5900.
• Dovolite omrežnim napravam povezavo: izklopljeno. Ko je API omogočen, se veže na 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 izbira, ker API nima preverjanja pristnosti in vključuje postopke, ki lahko premaknejo stroj 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. Možnost 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 (ali 127.0.0.1), ko je možnost Dovolite omrežnim napravam povezavo izklopljena. Ko je vklopljena, je strežnik dosegljiv na naslovu LAN tega računalnika iz katere koli naprave v omrežju.

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

Preverjanje pristnosti

Ni ga. API nima žetona, ključa ali prijave.

• Pri vezavi na localhost je meja model dostopa na ravni operacijskega sistema: kateri koli proces v vašem računalniku lahko komunicira z API-jem.
• Ko je omrežna vezava omogočena, lahko z API-jem komunicira kdor koli v istem omrežju. Način omrežne vezave uporabljajte samo v zaupanja vrednih omrežjih Wi-Fi.

Oblika zahtev

Vsa telesa zahtev POST/PATCH/PUT so JSON:

Content-Type: application/json

Poizvedbeni nizi so preprosti pari ključ=vrednost. Odseki poti so kodirani z URL kot običajno.

Ovojnica odgovora

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

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

Napake vrnejo enotno ovojnico:

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

error.code je ena od teh vrednosti:

Napake, ki zahtevajo potrditev

Majhno število postopkov lahko premakne stroj 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, pri čemer navedeno zastavico nastavite na true. Trenutno se uporabljajo zastavice confirm_motion, confirm_laser_on, confirm_raw_gcode in confirm_air_assist.

Skupine končnih točk

Referenčne strani za posamezne vire so še v izdelavi; do takrat si oglejte shemo zmogljivosti agenta.

Odkrijte trenutni vmesnik

Najhitreje si ogledate, kaj omogoča vaša nameščena različica:

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

To vrne celotno shemo zmogljivosti, vključno z vsemi končnimi točkami, njihovimi parametri in obliko odgovorov. Shema je merodajen opis, ta stran pa je njen vodnik.

Za pregled stanja:

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

Za pisno razlago upravljanja aplikacije:

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

Različice

Vse poti so pod /api/v1. Nezdružljive spremembe bodo ob uvedbi vključene v /api/v2. Dopolnilne spremembe, kot so nove končne točke in nova neobvezna polja, so vključene v v1 brez povečanja različice.

Povezano

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