HTTP API

HTTP API je integrační rozhraní pro Beam Bench. Desktopová aplikace, CLI i libovolný externí klient komunikují se stejnými cestami. Pokud potřebujete Beam Bench používat v prostředí mimo CLI (webová aplikace, integrační server, mobilní aplikace nebo vlastní nástroje), použijte přímo API.

API je dodáváno s desktopovou aplikací a běží v rámci jejího procesu. Není třeba instalovat samostatnou službu.

Výchozí nastavení a zabezpečení

V aktuálním sestavení je místní API server dodáván s tímto nastavením:

• Místní API: vypnuto.
• Port API: 5900.
• Povolit zařízení v síti: vypnuto. Když je API povoleno, naslouchá na 127.0.0.1 a přijímá připojení pouze z tohoto počítače.

API nenaslouchá připojením, dokud jeho použití nepovolíte. Povolení síťového přístupu vyžaduje samostatné potvrzení, protože API nevyžaduje ověření a obsahuje operace, které mohou pohybovat strojem a spustit laser.

Chcete-li API používat, změňte jeho nastavení v části Nastavení → Obecné:

1. Otevřete desktopovou aplikaci.
2. Úpravy → Nastavení → Obecné.
3. Zapněte Místní API.
4. Povolit zařízení v síti ponechte vypnuté, pokud se nemusí připojit jiné důvěryhodné zařízení.

Změny se projeví okamžitě; restart není potřeba.

Základní URL

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

<host> je localhost (nebo 127.0.0.1), pokud je Povolit zařízení v síti vypnuté. Když je zapnuté, server je dostupný na LAN IP adrese počítače z libovolného zařízení v síti.

Portu lze nastavit v části Nastavení → Obecné; výchozí hodnota je 5900.

Ověřování

Žádné. API nemá token, klíč ani přihlášení.

• Při vazbě na localhost je hranicí přístupu model přístupu na úrovni operačního systému: s API může komunikovat libovolný proces na vašem počítači.
• Při povolené síťové vazbě může s API komunikovat kdokoli ve stejné síti. Režim síťové vazby nepoužívejte v nedůvěryhodných sítích Wi-Fi.

Formát požadavku

Těla všech požadavků POST/PATCH/PUT jsou ve formátu JSON:

Content-Type: application/json

Řetězce dotazu mají plochý formát key=value. Segmenty cesty se kódují jako obvykle v URL.

Obálka odpovědi

Úspěšné odpovědi vracejí přímo tělo zdroje bez obálky:

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

Chyby vracejí jednotnou obálku:

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

error.code je jedna z těchto hodnot:

Chyby vyžadující potvrzení

Malá skupina operací může pohybovat strojem nebo spustit laser. Tyto koncové body vyžadují v těle požadavku explicitní příznak potvrzení. Pokud chybí, API vrátí 428 Precondition Required:

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

Odešlete požadavek znovu s pojmenovaným příznakem nastaveným na true. Aktuálně se používají příznaky confirm_motion, confirm_laser_on, confirm_raw_gcode a confirm_air_assist.

Skupiny koncových bodů

Referenční stránky pro jednotlivé zdroje se stále připravují; do té doby nahlédněte do schématu možností agenta.

Zjištění aktuálního rozhraní

Nejrychlejší způsob, jak zjistit, co vaše nainstalovaná verze poskytuje:

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

Tento příkaz vrátí úplné schéma možností včetně všech koncových bodů, jejich parametrů a tvaru odpovědí. Schéma je autoritativním popisem; tato stránka slouží jako průvodce.

Pro kontrolu stavu:

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

Písemný úvod k ovládání aplikace:

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

Verzování

Všechny cesty jsou pod /api/v1. Zpětně nekompatibilní změny budou při jejich zavedení umístěny pod /api/v2. Doplňující změny (nové koncové body, nová volitelná pole) se vydávají ve v1 bez zvýšení verze.

Související informace

• Průvodce používáním HTTP API: úvod ve stylu tutoriálu s praktickými příklady.
• Jak CLI a aplikace sdílejí stav: model konzistence těchto koncových bodů.
• Nastavení → Obecné: místo, kde lze povolit API a zvolit port.