API HTTP

L'API HTTP è l'interfaccia di integrazione per Beam Bench. L'app desktop, la CLI e qualsiasi client esterno comunicano tutti con gli stessi percorsi. Se hai un caso d'uso che richiede Beam Bench in un ambiente diverso dalla CLI (app web, server di integrazione, app mobile, i tuoi strumenti), usa direttamente l'API.

L'API viene distribuita con l'app desktop ed è eseguita nel processo. Non è necessario installare un servizio separato.

Impostazioni predefinite e sicurezza

Nella build corrente, il server API locale viene distribuito con queste impostazioni:

• API locale: disattivata.
• Porta API: 5900.
• Consenti la connessione ai dispositivi di rete: disattivata. Quando l'API è abilitata, si associa a 127.0.0.1 e accetta connessioni solo da questo computer.

L'API non resta in ascolto per le connessioni finché non scegli di attivarla. L'abilitazione dell'accesso di rete richiede un consenso separato perché l'API non dispone di autenticazione e include operazioni che possono spostare la macchina e attivare il laser.

Per usare l'API, modifica le sue impostazioni da Impostazioni → Generali:

1. Apri l'app desktop.
2. Modifica → Impostazioni → Generali.
3. Attiva API locale.
4. Lascia disattivata Consenti la connessione ai dispositivi di rete, a meno che non debba connettersi un altro dispositivo attendibile.

Le modifiche hanno effetto immediato; non è necessario riavviare.

URL di base

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

<host> è localhost (oppure 127.0.0.1) quando Consenti la connessione ai dispositivi di rete è disattivata. Quando è attivata, il server è raggiungibile all'indirizzo IP LAN della macchina da qualsiasi dispositivo della rete.

La porta è configurabile in Impostazioni → Generali; 5900 è il valore predefinito.

Autenticazione

Nessuna. L'API non dispone di token, chiave o accesso.

• Con l'associazione a localhost, il modello di accesso a livello di sistema operativo costituisce il confine: qualsiasi processo sulla tua macchina può comunicare con l'API.
• Con l'associazione di rete abilitata, chiunque nella stessa rete può comunicare con l'API. Non usare la modalità di associazione di rete su una rete Wi-Fi non attendibile.

Formato delle richieste

Tutti i corpi POST/PATCH/PUT sono JSON:

Content-Type: application/json

Le stringhe di query sono coppie chiave=valore semplici. I segmenti di percorso sono codificati come URL secondo la consuetudine.

Involucro della risposta

Le risposte riuscite restituiscono direttamente il corpo della risorsa, senza involucro:

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

Gli errori restituiscono un involucro uniforme:

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

error.code è uno dei seguenti:

Errori che richiedono conferma

Un piccolo insieme di operazioni può spostare la macchina o attivare il laser. Questi endpoint richiedono un flag di conferma esplicito nel corpo della richiesta. Se manca, l'API restituisce 428 Precondition Required:

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

Invia di nuovo la richiesta con il flag indicato impostato su true. I flag attualmente in uso sono confirm_motion, confirm_laser_on, confirm_raw_gcode e confirm_air_assist.

Gruppi di endpoint

Le pagine di riferimento per risorsa sono in corso di sviluppo; nel frattempo consulta lo schema delle capacità dell'agente.

Scopri l'interfaccia disponibile

Il modo più rapido per vedere cosa espone la versione installata:

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

Restituisce lo schema completo delle capacità, inclusi ogni endpoint, i relativi parametri e la forma della risposta. Lo schema è la descrizione autorevole; questa pagina è una guida.

Per l'ispezione dello stato:

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

Per una guida scritta su come controllare l'app:

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

Versionamento

Tutti i percorsi sono sotto /api/v1. Le modifiche incompatibili saranno in /api/v2 quando verranno introdotte. Le modifiche additive (nuovi endpoint, nuovi campi facoltativi) vengono distribuite in v1 senza incremento di versione.

Correlati

• Guida all'uso dell'API HTTP: introduzione in stile tutorial con esempi svolti.
• Come CLI e app condividono lo stato: il modello di coerenza alla base di questi endpoint.
• Impostazioni → Generali: dove abilitare l'API e scegliere la porta.