HTTP API

HTTP API on Beam Benchin integrointirajapinta. Useimmat CLI-komennot ja ulkoiset asiakkaat käyttävät näitä reittejä. Työpöydän käyttöliittymä kutsuu jaettua palvelua Tauri IPC:n kautta eikä tarvitse HTTP-palvelinta normaalissa käytössä. Jos haluat käyttää Beam Benchiä ympäristössä, joka ei ole CLI (verkkosovellus, integraatiopalvelin, mobiilisovellus tai omat työkalusi), käytä APIa suoraan.

API toimitetaan työpöytäsovelluksen mukana ja se suoritetaan sovelluksen sisällä. Erillistä palvelua ei tarvitse asentaa.

Oletukset ja tietoturva

Nykyisessä koontiversiossa paikallinen API-palvelin toimitetaan näillä asetuksilla:

• Paikallinen API: pois käytöstä.
• API-portti: 5900.
• Salli verkkolaitteet: pois käytöstä. Kun API on käytössä, se sitoutuu osoitteeseen 127.0.0.1 ja hyväksyy yhteydet vain tästä tietokoneesta.

API ei kuuntele yhteyksiä, ennen kuin otat sen käyttöön. Verkkoyhteyksien salliminen on erillinen käyttöönotto, koska APIlla ei ole todennusta ja se sisältää toimintoja, jotka voivat liikuttaa konetta ja käynnistää laserin.

Käytä APIa muuttamalla sen asetuksia kohdassa Asetukset → Yleiset:

1. Avaa työpöytäsovellus.
2. Muokkaa → Asetukset → Yleiset.
3. Ota Paikallinen API käyttöön.
4. Jätä Salli verkkolaitteet pois käytöstä, ellei jonkin muun luotetun laitteen tarvitse muodostaa yhteyttä.

Muutokset tulevat voimaan heti, uudelleenkäynnistystä ei tarvita.

Perus-URL-osoite

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

<host> on localhost (tai 127.0.0.1), kun Salli verkkolaitteet on pois käytöstä. Kun asetus on käytössä, palvelin on tavoitettavissa koneen lähiverkon IP-osoitteessa kaikilta verkon laitteilta.

Portti voidaan määrittää kohdassa Asetukset → Yleiset; 5900 on oletus.

Todennus

Ei mitään. APIssa ei ole tunnusta, avainta eikä kirjautumista.

• Kun sidonta on localhost, käyttöjärjestelmän käyttöoikeusmalli on rajana: mikä tahansa koneesi prosessi voi keskustella API:n kanssa.
• Kun verkkosidonta on käytössä, kuka tahansa samassa verkossa oleva voi keskustella API:n kanssa. Älä käytä verkkosidontatilaa epäluotettavassa Wi-Fi-verkossa.

Pyyntöjen muoto

Kaikki POST/PATCH/PUT-rungot ovat JSON-muotoisia:

Content-Type: application/json

Kyselymerkkijonot ovat litteitä key=value-pareja. Polun osat koodataan URL-osoitteiden tapaan.

Vastauskuori

Onnistuneet vastaukset palauttavat resurssin rungon suoraan ilman kuorta:

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

Virheet palauttavat yhdenmukaisen kuoren:

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

error.code on yksi seuraavista:

Vahvistusta edellyttävät virheet

Pieni joukko toimintoja voi liikuttaa konetta tai käynnistää laserin. Nämä päätepisteet edellyttävät pyyntörungossa eksplisiittistä vahvistuslippua. Jos lippu puuttuu, API palauttaa virheen 428 Precondition Required:

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

Lähetä pyyntö uudelleen niin, että nimetty lippu on asetettu arvoon true. Käytössä olevat liput ovat confirm_motion, confirm_laser_on, confirm_raw_gcode ja confirm_air_assist.

Samanaikaiset projektimuokkaukset

Suunnittelutapahtumat vertaavat tallennettua projektia sitoutushetkellä. Samanaikainen muokkaus, projektin vaihtaminen tai sulkeminen voi palauttaa virheen stale_revision. Päivitä tila ja arvioi muutos uudelleen ennen uutta yritystä. Älä toista vanhaa projektitilannekuvaa sokeasti uudemman työn päälle.

Päätepisteryhmät

Resurssikohtaiset viitesivut ovat vielä työn alla. Tutustu sillä välin agentin ominaisuusskeemaan.

Käytössä olevan rajapinnan selvittäminen

Nopein tapa nähdä, mitä asennettu versiosi tarjoaa:

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

Tämä palauttaa koko ominaisuusskeeman, mukaan lukien kaikki päätepisteet, niiden parametrit ja vastausten rakenteen. Skeema on auktoritatiivinen kuvaus; tämä sivu on sen käyttöopas.

Tilatietojen tarkastelua varten:

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

Sovelluksen ohjaamista kuvaavaa kirjallista opastusta varten:

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

Versiointi

Kaikki reitit ovat polun /api/v1 alla. Rikkovat muutokset sijoitetaan tarvittaessa polkuun /api/v2. Lisäävät muutokset, kuten uudet päätepisteet ja uudet valinnaiset kentät, toimitetaan versiossa v1 ilman versionumeron muutosta.

Aiheeseen liittyvää

• HTTP API -opas: opastetyylinen johdanto käytännön esimerkkeineen.
• Miten CLI ja sovellus jakavat tilan: näiden päätepisteiden taustalla oleva yhdenmukaisuusmalli.
• Asetukset → Yleiset: API:n käyttöönotto ja portin valinta.