API HTTP

L’API HTTP est la surface d’intégration de Beam Bench. L’application de bureau, la CLI et tout client externe communiquent tous avec les mêmes routes. Si votre cas d’utilisation nécessite Beam Bench dans un environnement autre que la CLI (application web, serveur d’intégration, application mobile, vos propres outils), utilisez directement l’API.

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

Valeurs par défaut et sécurité

Dans la version actuelle, le serveur d’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’activation de l’accès réseau nécessite une autorisation distincte, car l’API n’est pas authentifiée et inclut des opérations capables de déplacer la machine et d’activer le laser.

Pour utiliser l’API, modifiez ses paramètres dans 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 ; aucun redémarrage n’est nécessaire.

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 LAN 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 ne possède 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 sur votre machine peut communiquer avec l’API.
• Avec la liaison réseau activée, toute personne sur le même réseau peut communiquer avec l’API. N’utilisez pas le mode de liaison réseau sur un 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 de simples paires clé=valeur. Les segments de chemin sont encodés en URL comme d’habitude.

Enveloppe de réponse

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

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

Les erreurs renvoient une enveloppe uniforme :

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

error.code est l’un des suivants :

Erreurs nécessitant une confirmation

Un petit ensemble d’opérations peut déplacer la machine ou activer le laser. Ces points de terminaison exigent un indicateur de confirmation explicite dans le corps de la requête. S’il est absent, 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.

Groupes de points de terminaison

Les pages de référence par ressource sont en cours d’élaboration ; consultez entre-temps le schéma des capacités de l’agent.

Découvrir la surface disponible

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, y compris chaque point de terminaison, ses paramètres et la forme de sa réponse. Le schéma est la description faisant autorité ; cette page sert de guide.

Pour l’inspection de l’état :

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

Pour une présentation écrite de la façon 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 sous /api/v2 lorsqu’ils surviendront. Les changements additifs (nouveaux points de terminaison, nouveaux champs facultatifs) sont fournis dans v1 sans augmentation de version.

Liens connexes

• Guide d’utilisation de l’API HTTP : une introduction de type tutoriel avec des exemples détaillés.
• Comment la CLI et l’application partagent l’état : le modèle de cohérence derrière ces points de terminaison.
• Paramètres → Général : où activer l’API et choisir le port.