API HTTP

L'API HTTP è la superficie di integrazione di Beam Bench. La maggior parte dei comandi CLI e dei client esterni usa queste route. Il frontend desktop chiama il servizio condiviso tramite Tauri IPC e non richiede il server HTTP per l'uso normale. Se hai un caso d'uso che richiede Beam Bench in un ambiente non CLI, come un'app web, un server di integrazione, un'app mobile o i tuoi strumenti, usa direttamente l'API.

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

Impostazioni predefinite e sicurezza

Nella build attuale, 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 ascolta connessioni finché non scegli di abilitarla. L'accesso alla rete richiede una scelta separata perché l'API non usa autenticazione e include operazioni che possono muovere la macchina e attivare il laser.

Per usare l'API, modifica le relative 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 e non richiedono il riavvio.

URL di base

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

<host> è localhost (o 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 usa token, chiavi o accesso.

• Con l'associazione a localhost, il modello di accesso a livello di sistema operativo costituisce il confine: qualsiasi processo sul computer può comunicare con l'API.
• Con l'associazione alla rete attivata, chiunque si trovi sulla stessa rete può comunicare con l'API. Non usare la modalità di associazione alla rete su reti Wi-Fi non attendibili.

Formato delle richieste

Tutti i corpi delle richieste POST/PATCH/PUT sono JSON:

Content-Type: application/json

Le stringhe di query sono coppie piatte chiave=valore. I segmenti del percorso vengono codificati nell'URL come di consueto.

Involucro delle risposte

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

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

Gli errori restituiscono un involucro uniforme:

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

error.code può essere uno dei seguenti:

Errori che richiedono conferma

Un piccolo insieme di operazioni può muovere 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 nuovamente 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.

Modifiche simultanee al progetto

Le transazioni di Design confrontano il progetto acquisito al momento del commit. Una modifica simultanea, un cambio di progetto o una chiusura possono restituire stale_revision. Aggiorna lo stato e rivaluta la modifica prima di riprovare. Non riprodurre alla cieca una vecchia istantanea del progetto sopra un lavoro più recente.

Gruppi di endpoint

Le pagine di riferimento per singola risorsa sono ancora in lavorazione; nel frattempo consulta lo schema delle funzionalità dell'agente.

Scoprire la superficie attiva

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 funzionalità, inclusi tutti gli endpoint, i relativi parametri e la forma delle risposte. Lo schema è la descrizione autorevole; questa pagina ne è una guida.

Per l'introspezione 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

Tutte le route sono contenute in /api/v1. Quando si verificano modifiche incompatibili, vengono usate /api/v2. Le modifiche additive, come nuovi endpoint e nuovi campi facoltativi, vengono distribuite in v1 senza incrementare la 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.