La API de Insight: Parte 1

Acabamos de lanzar la versión 0 (Alpha) de la API de Insight. Los shapers/reguladores de LibreQoS también tienen una API, pero ese será el tema de futuras publicaciones. En esta ocasión, hablaremos exclusivamente de la API de Insight.

Requisitos previos

Para poder usar la API de Insight, necesita:

• Tener LibreQoS 1.5 RC2 o una versión posterior instalada en una o más cajas reguladoras.
• Una cuenta activa de Insight, a la cual LibreQoS esté enviando datos.

Accediendo a la API

La API de Insight es una API de tipo REST, accesible a través de HTTPS. La documentación completa de Swagger se encuentra aquí: https://insight-api.libreqos.com/api-docs/

Los endpoints disponibles al momento de escribir esto son:

• GET /health - Verifica el estado de la API.
• POST /shaper_stats - Obtiene estadísticas de un shaper (caja reguladora) específico.
• POST /site_stats - Obtiene estadísticas de un sitio específico.
• POST /circuit_stats - Obtiene estadísticas de un circuito específico.

Cada uno de estos endpoints tiene un tipo de Request (solicitud en JSON) y un tipo de Response (respuesta en JSON).

Si ya ha trabajado con APIs RESTful antes, todo esto le resultará muy familiar, ¡y prácticamente estará listo para comenzar!

Autenticación

Cada solicitud a la API de Insight debe estar autenticada usando su clave de Insight. Puede encontrarla en su archivo /etc/lqos.conf dentro de la sección [long_term_stats], en el campo license_key; o bien en la interfaz de usuario de LibreQoS, en Configuration -> LibreQoS Insight.

Una vez que tenga esta clave, debe incluirla en el encabezado x-bearer de cada solicitud.

IDs de nodos Shaper

También necesitará conocer el node_id de su shaper o shapers. Puede obtenerlo en la parte superior de su archivo /etc/lqos.conf como node_id = "<su id>", o en la interfaz de usuario de LibreQoS en Configuration -> General.

Realizando su primera solicitud

La manera más sencilla de probar la API es abriendo la documentación ( https://insight-api.libreqos.com/api-docs/ ) en su navegador. Haga clic en el endpoint /health y luego en “Try it Out”:

Introduzca su clave de licencia en el campo x-bearer y haga clic en “Execute”. Debería ver una respuesta 200 con un cuerpo JSON simple:

{
  "status": "ok"
}

¡Felicidades! Acaba de realizar su primera solicitud a la API de Insight.

Solicitando el rendimiento de un Shaper

Es prácticamente imposible adivinar en qué lenguaje prefieren trabajar, así que elegí Python en un Jupyter Notebook. Los científicos de datos pasan mucho tiempo en Jupyter Notebooks—es una excelente forma de explorar datos.

Paso 1 - Importe algunas bibliotecas:

import time
import requests
import matplotlib.pyplot as plt

time permite obtener marcas de tiempo UNIX (segundos desde el epoch). requests es una gran biblioteca HTTP para Python, y matplotlib es una biblioteca de gráficos.

Paso 2 - Configure algunas variables:

NODE_ID="my_node_id"
LICENSE_KEY="my_license_key"

Luego defina el período de tiempo que desea consultar:

START_TIME = int(time.time() - 60*60)
END_TIME = int(time.time())

Esto define un rango que comienza hace una hora y termina en el momento actual.

Paso 3 - Cree el cuerpo de la solicitud y el encabezado:

request = { 
    "shaper_node" : NODE_ID, 
    "num_entries": 200, # How many data points to return
    "start_unix": START_TIME, 
    "end_unix": END_TIME 
}
headers = {"x-bearer": LICENSE_KEY}

Luego haga la solicitud:

response = requests.post("https://insight-api.libreqos.com/shaper_stats", json=request, headers=headers)
data = response.json()

Finalmente, podemos extraer los datos de rendimiento y graficarlos:

# Extraer los datos para graficar
ticks = data['ticks']
bytes_down = data['bytes_per_second_down_median']

# Crear el gráfico
plt.figure(figsize=(10, 6))
plt.plot(ticks, bytes_down)
plt.xlabel('Ticks')
plt.ylabel('Bytes Per Second Down (Median)')
plt.title('Download Speed Over Time')
plt.grid(True)
plt.show()

Esto produce un gráfico con la velocidad de descarga durante la última hora:

¿Qué sigue?

Seguiremos agregando más endpoints y funciones a la API con el tiempo. Por ahora, la pelota está en su cancha: ya tiene los datos, ¡así que construya algo increíble con ellos!

• Puede utilizar datos de circuitos en un portal orientado al cliente.
• Puede integrar los datos con n8n u otras herramientas low-code para automatizar reportes o configurar alertas de eventos.
• Puede utilizar los datos en su propia solución de paneles o dashboards.

Las posibilidades son infinitas. ¡Feliz programación!