API HTTP

L’API HTTP est l’interface d’intégration de Beam Bench. La plupart des commandes de la CLI et des clients externes utilisent ces routes. Le frontend de bureau appelle le service partagé via Tauri IPC et n’a pas besoin du serveur HTTP pour une utilisation normale. Si votre cas d’utilisation nécessite Beam Bench dans un environnement sans CLI, comme une application web, un serveur d’intégration, une application mobile ou vos propres outils, utilisez directement l’API.

L’API est fournie avec l’application de bureau et s’exécute dans le processus. Aucun service séparé n’est à installer.

Valeurs par défaut et sécurité

Dans la version actuelle, le serveur API local est fourni avec les paramètres suivants :

• API locale : désactivée.
• Port de l’API : 5900.
• Autoriser les appareils du réseau : désactivé. Lorsque l’API est activée, elle se lie à 127.0.0.1 et accepte uniquement les connexions provenant de cet ordinateur.

L’API n’écoute aucune connexion tant que vous ne l’avez pas activée. L’accès réseau est une activation distincte, car l’API ne dispose d’aucune authentification et comprend des opérations capables de déplacer la machine et de déclencher le laser.

Pour utiliser l’API, modifiez ses paramètres depuis Paramètres → Général :

1. Ouvrez l’application de bureau.
2. Modifier → Paramètres → Général.
3. Activez API locale.
4. Laissez Autoriser les appareils du réseau désactivé, sauf si un autre appareil de confiance doit se connecter.

Les modifications prennent effet immédiatement, sans redémarrage.

URL de base

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

<host> est localhost ou 127.0.0.1 lorsque Autoriser les appareils du réseau est désactivé. Lorsqu’il est activé, le serveur est accessible à l’adresse IP du réseau local de la machine depuis n’importe quel appareil du réseau.

Le port est configurable dans Paramètres → Général ; 5900 est la valeur par défaut.

Authentification

Aucune. L’API n’a ni jeton, ni clé, ni connexion.

• Avec une liaison localhost, le modèle d’accès au niveau du système d’exploitation constitue la limite : tout processus de votre machine peut communiquer avec l’API.
• Avec la liaison réseau activée, toute personne présente sur le même réseau peut communiquer avec l’API. N’utilisez pas le mode de liaison réseau sur un réseau Wi-Fi non fiable.

Format des requêtes

Tous les corps POST/PATCH/PUT sont au format JSON :

Content-Type: application/json

Les chaînes de requête sont des paires clé=valeur simples. Les segments de chemin sont encodés dans les URL selon les règles habituelles.

Enveloppe des réponses

Les réponses réussies renvoient directement le corps de la ressource, sans enveloppe :

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

Les erreurs renvoient une enveloppe uniforme :

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

error.code peut prendre l’une des valeurs suivantes :

Erreurs nécessitant une confirmation

Un petit nombre d’opérations peuvent déplacer la machine ou déclencher le laser. Ces points d’accès nécessitent un indicateur de confirmation explicite dans le corps de la requête. S’il manque, l’API renvoie 428 Precondition Required :

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

Renvoyez la requête avec l’indicateur nommé défini sur true. Les indicateurs actuellement utilisés sont confirm_motion, confirm_laser_on, confirm_raw_gcode et confirm_air_assist.

Modifications simultanées d’un projet

Les transactions de conception comparent le projet capturé au moment de la validation. Une modification simultanée, un changement de projet ou une fermeture peut renvoyer stale_revision. Actualisez l’état et réévaluez la modification avant de réessayer. Ne rejouez pas aveuglément un ancien instantané du projet par-dessus un travail plus récent.

Groupes de points d’accès

Les pages de référence par ressource sont encore en cours de rédaction ; consultez en attendant le schéma des capacités de l’agent.

Découvrir l’interface active

Le moyen le plus rapide de voir ce que votre version installée expose :

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

Cette commande renvoie le schéma complet des capacités, avec chaque point d’accès, ses paramètres et la forme de sa réponse. Le schéma constitue la description faisant autorité ; cette page sert de guide.

Pour examiner l’état :

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

Pour obtenir une présentation écrite de la manière de piloter l’application :

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

Gestion des versions

Toutes les routes se trouvent sous /api/v1. Les changements incompatibles seront placés dans /api/v2 lorsqu’ils se produiront. Les changements additifs, comme les nouveaux points d’accès ou les nouveaux champs facultatifs, sont publiés dans v1 sans changement de version.

Pages associées

• Guide d’utilisation de l’API HTTP : introduction sous forme de tutoriel avec des exemples détaillés.
• Comment la CLI et l’application partagent leur état : modèle de cohérence sous-jacent à ces points d’accès.
• Paramètres → Général : emplacement d’activation de l’API et de sélection du port.