API REST

Todo lo que hace la interfaz de NetEdge pasa por una API REST en JSON bajo /api/v1 — la propia aplicación web es un cliente más de esa API. Si puedes hacer algo desde la barra lateral, también puedes automatizarlo por HTTP: crear nodos desde un script de aprovisionamiento, lanzar un despliegue desde tu propio pipeline, o volcar el inventario a otra herramienta.

Esta página cubre la API del producto base. Si tu licencia incluye módulos adicionales (recetas en cascada P2P, tareas post-clonación, SNMP, RBAC…), esos módulos añaden sus propios endpoints — se documentarán aquí en próximas actualizaciones de esta guía.

Convenciones

• Base URL — la misma dirección que usas para entrar a la interfaz (p. ej. http://localhost:8080).
• Prefijo — todos los endpoints de negocio van bajo /api/v1.
• Formato — JSON en cuerpo de petición y respuesta, salvo la subida y descarga de imágenes (binario/multipart) y los streams en vivo (Server-Sent Events).
• Códigos de estado — 200/201 éxito, 400 payload inválido, 401 token ausente o caducado, 403 rol insuficiente o funcionalidad no incluida en tu licencia, 404 recurso inexistente, 409 conflicto de estado (por ejemplo, un despliegue ya en curso), 429 límite de peticiones superado.

Autenticación

La mayoría de endpoints exigen un token JWT Bearer. Consíguelo con tu usuario y contraseña de siempre:

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"netedge"}' | jq -r .token)

Y úsalo en cada petición posterior:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/auth/me

El token caduca a las 24 horas. Si tu instalación tiene el autorregistro activo (ver Configuración), también existen rutas públicas sin token para recuperación de contraseña y alta de cuenta: POST /api/v1/auth/forgot, POST /api/v1/auth/reset y POST /api/v1/auth/register.

Estado en vivo sin sondeo (Server-Sent Events)

Todo lo que la interfaz muestra "en vivo" — el estado de la flota, el progreso de un despliegue, el registro de log — viaja por SSE: el servidor empuja un snapshot nuevo solo cuando algo cambia, en vez de que el cliente pregunte a intervalos. Como el estándar EventSource no permite mandar cabeceras, primero se pide un ticket de un solo uso:

SSE_TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/events/stream-token \
  -H "Authorization: Bearer $TOKEN" | jq -r .token)

curl -N "http://localhost:8080/api/v1/nodes/status/stream?token=$SSE_TOKEN"

Streams disponibles: GET /api/v1/events/stream (barra lateral, versión, resumen de licencia), GET /api/v1/nodes/status/stream (estado de la flota), GET /api/v1/deployments/progress/stream (progreso de despliegues en curso) y GET /api/v1/logs/stream (consola de log). Cada uno tiene un equivalente GET normal sin stream como alternativa de reserva.

Infraestructura

Ver la guía de uso completa en Infraestructura.

• GET/POST /api/v1/zones, GET/PUT/DELETE /api/v1/zones/:id
• GET/POST /api/v1/subzones, GET/PUT/DELETE /api/v1/subzones/:id
• GET/POST /api/v1/groups, GET/PUT/DELETE /api/v1/groups/:id
• GET/POST /api/v1/nodes, GET/PUT/DELETE /api/v1/nodes/:id
• GET /api/v1/nodes/status — snapshot del estado de toda la flota
• POST /api/v1/nodes/:id/wol, POST /api/v1/groups/:id/wol, POST /api/v1/zones/:id/wol — Wake-on-LAN inmediato
• GET/POST /api/v1/wol-schedules, GET/PUT/DELETE /api/v1/wol-schedules/:id — Wake-on-LAN programado (una vez o recurrente, expresión cron)
• GET/PUT /api/v1/node-capture/:kind/:id — captura automática de equipos desconocidos hacia una zona/subzona/grupo
• GET /api/v1/history/node/:id, GET /api/v1/history/group/:id, POST /api/v1/history/rollback — historial de despliegues y capturas

Cada nodo admite un array libre de etiquetas ("tags": ["aula-3"] en el cuerpo de creación/edición). Para desplegar por etiqueta: resuelve los nodos con GET /api/v1/nodes/tags (catálogo de etiquetas existentes) y POST /api/v1/nodes/by-tags ({"tags":["aula-3"],"match_mode":"any"} o "all", devuelve {node_ids, nodes}), y pasa esos node_ids a la creación del despliegue de siempre.

Ejemplo — crear un nodo:

curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"pc-aula-01","mac":"AA:BB:CC:DD:EE:FF","ip":"192.168.1.10","group_id":"<group-id>"}'

Imágenes

Ver la guía de uso completa en Imágenes.

• GET/POST /api/v1/images — listar / subir (multipart)
• GET/DELETE /api/v1/images/:id
• POST /api/v1/images/bulk-delete
• POST /api/v1/images/:id/download-token + GET /api/v1/images/:id/download?token=… — descarga con token temporal, sin exponer tu sesión

curl -X POST http://localhost:8080/api/v1/images \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Ubuntu 22.04 Aula 1" \
  -F "os=Ubuntu 22.04" \
  -F "file=@imagen.raw.zst"

Recetas

Ver la guía de uso completa en Recetas.

• GET/POST /api/v1/recipes, GET/PUT/DELETE /api/v1/recipes/:id
• POST /api/v1/recipes/from-preset — crea a partir de un preset (low_ram, balanced, fast)
• POST /api/v1/recipes/bulk-delete

curl -X POST http://localhost:8080/api/v1/recipes/from-preset \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Aula RAM baja","preset":"low_ram","uses_image":1}'

Despliegues

Ver la guía de uso completa en Despliegues.

• GET/POST /api/v1/deployments — listar / crear (por grupo o por una lista concreta de node_ids)
• GET/DELETE /api/v1/deployments/:id, DELETE /api/v1/deployments/:id/purge
• GET /api/v1/deployments/:id/cascade-plan — quién retransmite a quién
• GET /api/v1/deployments/:id/metrics-history — velocidad/progreso histórico para las gráficas
• GET /api/v1/console/nodes, POST /api/v1/console/:node_id/token + GET /api/v1/console/:node_id/ws — consola remota en vivo por WebSocket (el token de arriba es un ticket efímero de un solo uso, no tu JWT)

curl -X POST http://localhost:8080/api/v1/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "<recipe-id>",
    "group_id": "<group-id>",
    "image_id": "<image-id>",
    "post_action": "reboot"
  }'

Red

Ver la guía de uso completa en Red.

• GET/POST /api/v1/boot/ifaces, GET/PUT/DELETE /api/v1/boot/ifaces/:id
• PUT /api/v1/boot/ifaces/:id/dhcp, PUT /api/v1/boot/ifaces/:id/pxe
• GET /api/v1/boot/ifaces/:id/conflicts — escaneo en vivo de otro servidor DHCP/PXE en la misma subred
• GET /api/v1/boot/global + PUT /api/v1/boot/global/dhcp / .../pxe — la plantilla global de la que hereda cada interfaz

Log

Ver la guía de uso completa en Log.

• GET /api/v1/logs/stream — la misma consola en vivo que ves en la interfaz, como Server-Sent Events

Configuración

Ver la guía de uso completa en Configuración.

• GET/PUT /api/v1/settings/all, GET/PUT /api/v1/settings/image_dir, GET/PUT /api/v1/settings/timezone
• GET/PUT /api/v1/mail/settings + POST /api/v1/mail/test — servidor de correo saliente
• GET/PUT /api/v1/signup/settings, GET /api/v1/signup/pending, POST /api/v1/signup/users/:id/approve / .../reject — autorregistro
• GET /api/v1/updates/status, POST /api/v1/updates/check, POST /api/v1/updates/apply — auto-actualización
• GET /api/v1/config/backup (descarga un .netedge) y POST /api/v1/config/restore (multipart) — copia de seguridad completa

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/config/backup -o backup.netedge

Licencia

Ver la guía de uso completa en Licencia y soporte.

• GET /api/v1/license/status
• POST /api/v1/license/activate — cuerpo {"activation_key":"NE-XXXX-XXXX-XXXX"}
• POST /api/v1/license/heartbeat — fuerza una comprobación con el servidor de licencias ahora mismo
• GET/PUT /api/v1/license/server-url, GET/POST/DELETE /api/v1/license/server-urls

Usuarios

• GET/POST /api/v1/users, PUT/DELETE /api/v1/users/:id — cuentas y rol (admin o superadmin)

La API que hablan los propios clientes PXE

Cuando un equipo arranca por red, el propio netdd habla con NetEdge por HTTP, sin token — es la misma API que usarías tú, pero pensada para que la consuma la máquina que se está clonando:

• POST /api/v1/tracker/register / .../heartbeat, GET /api/v1/tracker/peers — registro de peers y progreso del enjambre P2P
• POST /api/v1/metrics/, POST /api/v1/summary/ — telemetría periódica y eventos de resumen del despliegue

No necesitas llamar a estos endpoints tú mismo — los describimos aquí para que entiendas de dónde salen las gráficas en vivo de Despliegues si alguna vez inspeccionas el tráfico de red.