API HTTP

La API HTTP es la interfaz de integración de Beam Bench. La aplicación de escritorio, la CLI y cualquier cliente externo utilizan las mismas rutas. Si necesitas usar Beam Bench en un entorno sin CLI (una aplicación web, un servidor de integración, una aplicación móvil o tus propias herramientas), utiliza la API directamente.

La API se incluye con la aplicación de escritorio y se ejecuta dentro de su proceso. No hay que instalar ningún servicio aparte.

Valores predeterminados y seguridad

En la versión actual, el servidor de la API local incluye estos ajustes:

• API local: desactivada.
• Puerto de la API: 5900.
• Permitir dispositivos de red: desactivado. Cuando la API está activada, se vincula a 127.0.0.1 y solo acepta conexiones desde este ordenador.

La API no escucha conexiones hasta que la activas expresamente. El acceso desde la red se activa por separado porque la API no requiere autenticación e incluye operaciones que pueden mover la máquina y disparar el láser.

Para utilizar la API, cambia sus ajustes en Configuración → General:

1. Abre la aplicación de escritorio.
2. Editar → Configuración → General.
3. Activa API local.
4. Mantén Permitir dispositivos de red desactivado salvo que otro dispositivo de confianza necesite conectarse.

Los cambios se aplican de inmediato, sin necesidad de reiniciar.

URL base

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

<host> es localhost (o 127.0.0.1) cuando Permitir dispositivos de red está desactivado. Cuando está activado, se puede acceder al servidor mediante la IP de la máquina en la red LAN desde cualquier dispositivo de la red.

El puerto se puede configurar en Configuración → General. El valor predeterminado es 5900.

Autenticación

Ninguna. La API no tiene token, clave ni inicio de sesión.

• Con la vinculación a localhost, el límite lo establece el modelo de acceso del sistema operativo: cualquier proceso de tu máquina puede comunicarse con la API.
• Con la vinculación a la red activada, cualquier persona de la misma red puede comunicarse con la API. No utilices el modo de vinculación a la red en una red Wi-Fi que no sea de confianza.

Formato de las solicitudes

Todos los cuerpos POST/PATCH/PUT son JSON:

Content-Type: application/json

Las cadenas de consulta usan pares simples clave=valor. Los segmentos de ruta se codifican para URL de la forma habitual.

Envoltorio de las respuestas

Las respuestas correctas devuelven directamente el cuerpo del recurso, sin envoltorio:

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

Los errores devuelven un envoltorio uniforme:

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

error.code puede ser uno de estos valores:

Errores que requieren confirmación

Un pequeño conjunto de operaciones puede mover la máquina o disparar el láser. Esos endpoints requieren un indicador de confirmación explícito en el cuerpo de la solicitud. Si falta, la API devuelve 428 Precondition Required:

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

Vuelve a enviar la solicitud con el indicador indicado establecido en true. Los indicadores que se utilizan actualmente son confirm_motion, confirm_laser_on, confirm_raw_gcode y confirm_air_assist.

Grupos de endpoints

Las páginas de referencia de cada recurso siguen en desarrollo. Mientras tanto, consulta el esquema de capacidades del agente.

Descubrir la interfaz activa

La forma más rápida de ver qué ofrece la versión que tienes instalada es:

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

Esto devuelve el esquema completo de capacidades, incluidos todos los endpoints, sus parámetros y la estructura de sus respuestas. El esquema es la descripción de referencia. Esta página sirve como guía.

Para consultar el estado:

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

Para obtener una guía escrita sobre cómo controlar la aplicación:

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

Control de versiones

Todas las rutas están bajo /api/v1. Cuando se produzcan cambios incompatibles, se incluirán en /api/v2. Los cambios aditivos (nuevos endpoints y nuevos campos opcionales) se publican en v1 sin cambiar la versión.

Contenido relacionado

• Guía de uso de la API HTTP: introducción práctica con ejemplos completos.
• Cómo comparten el estado la CLI y la aplicación: el modelo de coherencia en el que se basan estos endpoints.
• Configuración → General: dónde activar la API y elegir el puerto.