REST API o WebSocket

WLTE ofrece REST API y WebSocket. No se sustituyen entre sí: son dos canales diseñados para necesidades de integración distintas.

Modelo básico

REST API usa el modelo estándar de petición y respuesta. Tu servidor envía una petición HTTPS y WLTE devuelve una respuesta explícita. Sirve para listar y consultar recursos, enviar operaciones y leer sus resultados.

WebSocket usa un modelo de conexión persistente. Tu servidor crea primero un wsTicket de un solo uso mediante REST y después establece una conexión wss. Una vez establecida, esa misma conexión sirve para enviar peticiones y recibir eventos de dispositivo.

Diferencias principales

Dimensión	REST API	WebSocket
Conexión	Una petición HTTP independiente por llamada	Conexión persistente reutilizada en el tiempo
Interacción	Una petición, una respuesta	Envía peticiones, recibe respuestas y recibe eventos
Ideal para	Listas, paginación, configuración, envío de comandos, consulta de resultados	Consultas de estado en tiempo real, interacción de baja latencia, entrega de eventos
Modelo de fiabilidad	Cada petición tiene un resultado explícito y admite las reglas de reintento HTTP	La conexión puede caerse; no se garantiza la reproducción de los eventos ocurridos durante la caída
Autorización	Cada endpoint protegido valida los permisos actuales	La conexión requiere un ticket; las peticiones activas siguen validando los permisos de la operación
Protección de peticiones	Las consultas y las operaciones sobre dispositivos tienen límite de tasa	Las conexiones, los mensajes y las operaciones sobre dispositivos tienen límite de tasa
Coste de integración	Más sencillo, adecuado para la mayoría de integraciones de servidor	Más complejo: requiere heartbeat, reconexión y tratamiento idempotente de eventos

Cuándo usar REST API

Prefiere REST API cuando necesites:

• Mostrar los dispositivos de una cuenta
• Cargar dispositivos con paginación
• Consultar las definiciones de tipo de dispositivo
• Crear operaciones de relé, RS485 o configuración
• Consultar el resultado de un comando
• Ejecutar sincronizaciones programadas en el servidor
• Trabajar con códigos de estado HTTP y códigos de error de negocio claros

Flujo habitual:

Obtener access token
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

Cuándo usar WebSocket

Plantéate WebSocket cuando tu servidor necesite:

• Permanecer conectado y recibir eventos de dispositivo
• Consultar el estado en tiempo real de un dispositivo con baja latencia
• Mantener el estado de los dispositivos vivo dentro de un proceso de servicio
• Reducir la latencia de abrir conexiones HTTP repetidamente

Flujo habitual:

Obtener access token
-> POST /wlte/v1/ws/ticket
-> Conectar a wss://.../wlte/v1/ws?ticket=...
-> Enviar session.ping como heartbeat de aplicación
-> Enviar device.state.get para el estado en tiempo real de un dispositivo
-> Enviar device.operation.execute para operar el dispositivo
-> Recibir eventos de dispositivo

Combinación recomendada

La mayoría de integraciones en producción deberían usar ambos:

1. Usa REST API para la inicialización y la sincronización de respaldo.
2. Usa WebSocket para los cambios en tiempo real y las consultas de estado de un dispositivo.
3. Tras una desconexión de WebSocket o un reinicio del servicio, usa REST API para reconstruir la base de estado.
4. No dependas solo de los eventos WebSocket para el estado crítico de tu negocio: ten siempre forma de confirmarlo por REST API.

Errores habituales

Actualizar todos los dispositivos de la cuenta por WebSocket

No es recomendable. device.state.get es para el estado en tiempo real de un solo dispositivo y puede disparar una actualización real y los límites de tasa por dispositivo. Para listar los dispositivos de una cuenta usa Listar dispositivos (en inglés).

Dar por hecho que WebSocket nunca se desconecta

No lo des por hecho. Cambios de red, despliegues, proxies, reinicios del servicio y reinicios del proceso cliente pueden cerrar la conexión. El cliente debe implementar reconexión, heartbeat y tratamiento idempotente de eventos.

Sustituir todas las consultas de estado por eventos WebSocket

No es recomendable. WebSocket sirve para notificar en tiempo real, pero no debe ser la única fuente permanente de estado. Tras un hueco de estado, una recarga de página o un reinicio del servicio, vuelve a confirmar el estado con REST API o con device.state.get.

Tabla de decisión rápida

Necesidad	Recomendación
Primera integración o validación de la API	REST API
Mostrar una lista de dispositivos	REST API
El usuario abre el detalle de un dispositivo y lo actualiza	REST API GET /devices/{deviceId} o WS device.state.get
El servidor necesita eventos continuos de cambio	WebSocket
Ejecutar control de dispositivo	REST API, o device.operation.execute sobre una conexión WebSocket ya abierta
Consultar el resultado final de un comando	REST API
Recuperar el estado tras una desconexión de WebSocket	Resincroniza con REST API y continúa con WebSocket