API HTTP

La API HTTP es la superficie de integración de Beam Bench. La mayoría de los comandos de la CLI y los clientes externos usan estas rutas. La interfaz de escritorio llama al servicio compartido mediante IPC de Tauri y no requiere el servidor HTTP para el uso normal. Si tienes un caso de uso que necesita Beam Bench en un entorno que no sea la CLI, como una aplicación web, un servidor de integración, una 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 hay ningún servicio independiente que instalar.

Valores predeterminados y seguridad

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

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

La API no escucha conexiones hasta que optas por habilitarla. Permitir el acceso de red requiere una activació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. Mantén desactivada Permitir dispositivos de red a menos que otro dispositivo de confianza deba conectarse.

Los cambios tienen efecto 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 local, el modelo de acceso del sistema operativo es el límite: cualquier proceso de tu máquina puede comunicarse con la API.
• Con el enlace de red habilitado, cualquier persona de 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 las solicitudes

Todos los cuerpos POST/PATCH/PUT son JSON:

Content-Type: application/json

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

Envoltorio de respuesta

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

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

Los errores devuelven un envoltorio uniforme:

{
  "error": {
    "code": "invalid_input",
    "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 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 nombrado establecido en true. Los indicadores que se usan actualmente son confirm_motion, confirm_laser_on, confirm_raw_gcode y confirm_air_assist.

Ediciones simultáneas del proyecto

Las transacciones de Diseño comparan el proyecto capturado en el momento de confirmar los cambios. Una edición simultánea, un cambio de proyecto o un cierre puede devolver stale_revision. Actualiza el estado y vuelve a evaluar el cambio antes de reintentarlo. No reproduzcas a ciegas una instantánea antigua del proyecto sobre un trabajo más reciente.

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.

Descubrir la superficie 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 forma de sus respuestas. El esquema es la descripción autorizada; esta página es una guía del mismo.

Para inspeccionar el estado:

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

Para obtener una orientación escrita sobre cómo controlar la aplicación:

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

Versionado

Todas las rutas están bajo /api/v1. Los cambios incompatibles van en /api/v2 cuando ocurren. Los cambios aditivos, como endpoints nuevos y campos opcionales nuevos, se incorporan en v1 sin aumentar la versión.

Relacionado

• Guía para usar la API HTTP: una 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 habilitar la API y elegir el puerto.