HTTP API

HTTP API on Beam Benchin integrointirajapinta. Työpöytäsovellus, CLI ja kaikki ulkoiset asiakkaat käyttävät samoja reittejä. Jos tarvitset Beam Benchiä muussa kuin CLI-ympäristössä, kuten verkkosovelluksessa, integraatiopalvelimessa, mobiilisovelluksessa tai omassa työkalussasi, käytä APIa suoraan.

API toimitetaan työpöytäsovelluksen mukana, ja se toimii sovelluksen prosessissa. Erillistä palvelua ei tarvitse asentaa.

Oletukset ja tietoturva

Nykyisessä versiossa paikallinen API-palvelin toimitetaan seuraavilla asetuksilla:

• Paikallinen API: pois käytöstä.
• API-portti: 5900.
• Salli verkkolaitteet: pois käytöstä. Kun API on käytössä, se kuuntelee osoitteessa 127.0.0.1 ja hyväksyy yhteyksiä vain tältä tietokoneelta.

API ei kuuntele yhteyksiä, ennen kuin otat sen käyttöön. Verkkoyhteyksien salliminen on erillinen valinta, koska API ei käytä todennusta ja sisältää toimintoja, joilla konetta voidaan liikuttaa ja laser laukaista.

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 toisen luotetun laitteen tarvitse muodostaa yhteyttä.

Muutokset tulevat voimaan heti, eikä uudelleenkäynnistystä 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ä, palvelimeen voi muodostaa yhteyden koneen lähiverkon IP-osoitteella miltä tahansa verkon laitteelta.

Portin voi määrittää kohdassa Asetukset → Yleiset; oletusarvo on 5900.

Todennus

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

• Kun sidonta on localhostiin, käyttöjärjestelmän käyttöoikeusmalli muodostaa rajan: mikä tahansa koneellasi toimiva prosessi voi käyttää APIa.
• Kun verkkosidonta on käytössä, kuka tahansa samassa verkossa oleva voi käyttää APIa. Älä käytä verkkosidontatilaa epäluotettavassa Wi-Fi-verkossa.

Pyyntömuoto

Kaikkien POST-, PATCH- ja PUT-pyyntöjen rungot ovat JSON-muodossa:

Content-Type: application/json

Kyselymerkkijonot ovat muotoa avain=arvo. Polun osat koodataan URL-osoitteiden tapaan.

Vastauksen kääre

Onnistuneet vastaukset palauttavat resurssin rungon suoraan ilman käärettä:

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

Virheet palauttavat yhdenmukaisen kääreen:

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

error.code on jokin seuraavista:

Vahvistusta edellyttävät virheet

Pieni joukko toimintoja voi liikuttaa konetta tai laukaista laserin. Näissä päätepisteissä pyynnön runkoon on lisättävä erillinen vahvistuslippu. Jos lippu puuttuu, API palauttaa vastauksen 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. Tällä hetkellä käytössä olevat liput ovat confirm_motion, confirm_laser_on, confirm_raw_gcode ja confirm_air_assist.

Päätepisteryhmät

Resurssikohtaisten viitesivujen valmistelu on kesken. Tutustu sillä välin agentin ominaisuuksien skeemaan.

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 vastausmuodon. Skeema on auktoritatiivinen kuvaus; tämä sivu toimii sen käyttöoppaana.

Tilatietojen tarkastelu:

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

Kirjallinen opastus sovelluksen ohjaamiseen:

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 muuttamista.

Aiheeseen liittyvää

• HTTP API -käyttöopas: opastusmainen johdanto ja toimivia esimerkkejä.
• CLI:n ja sovelluksen yhteinen tila: näiden päätepisteiden taustalla oleva yhdenmukaisuusmalli.
• Asetukset → Yleiset: API:n käyttöönottopaikka ja portin valinta.