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 se comunican con las mismas rutas. Si tienes un caso de uso que requiere Beam Bench en un entorno que no sea la CLI (aplicación web, servidor de integración, aplicación móvil o tus propias herramientas), usa la API directamente.

La API se incluye con la aplicación de escritorio y se ejecuta dentro del proceso. No es necesario instalar ningún servicio independiente.

Valores predeterminados y seguridad

En la compilación actual, el servidor de API local se incluye con esta configuración:

• API local: desactivada.
• Puerto de la API: 5900.
• Permitir dispositivos de red: desactivada. Cuando la API está activada, se enlaza a 127.0.0.1 y acepta conexiones únicamente desde esta computadora.

La API no escucha conexiones hasta que la habilitas explícitamente. Activar el acceso de red requiere una confirmación independiente porque la API no tiene autenticación e incluye operaciones que pueden mover la máquina y activar el láser.

Para usar la API, cambia su configuración desde Configuración → General:

1. Abre la aplicación de escritorio.
2. Editar → Configuración → General.
3. Activa API local.
4. Deja Permitir dispositivos de red desactivada, a menos que otro dispositivo de confianza deba conectarse.

Los cambios se aplican de inmediato; no es necesario reiniciar.

URL base

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

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

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

Autenticación

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

• Con el enlace a localhost, el modelo de acceso del sistema operativo es el límite: cualquier proceso de tu computadora puede comunicarse con la API.
• Con el enlace de red activado, cualquier persona en la misma red puede comunicarse con la API. No uses el modo de enlace de red en una red Wi-Fi que no sea de confianza.

Formato de solicitud

Todos los cuerpos POST/PATCH/PUT son JSON:

Content-Type: application/json

Las cadenas de consulta son pares planos key=value. Los segmentos de ruta se codifican como URL de la forma habitual.

Contenedor de respuesta

Las respuestas exitosas devuelven directamente el cuerpo del recurso, sin contenedor:

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

Los errores devuelven un contenedor uniforme:

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

error.code puede ser uno de los siguientes:

Errores que requieren confirmación

Un pequeño conjunto de operaciones puede mover la máquina o activar el láser. Esos endpoints requieren una marca de confirmación explícita 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 la marca indicada establecida en true. Las marcas que se usan 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 aún están en desarrollo; mientras tanto, consulta el esquema de capacidades del agente.

Descubre la interfaz activa

La forma más rápida de ver lo que expone tu versión instalada:

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 es una guía.

Para inspeccionar 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. Los cambios incompatibles se incorporarán a /api/v2 cuando ocurran. Los cambios aditivos (nuevos endpoints o campos opcionales) se publican en v1 sin aumentar la versión.

Relacionado

• Guía para usar la API HTTP: introducción estilo tutorial con ejemplos desarrollados.
• Cómo comparten el estado la CLI y la aplicación: el modelo de coherencia detrás de estos endpoints.
• Configuración → General: dónde activar la API y elegir el puerto.