Cada gráfica del panel de CubePath tiene que salir de algún sitio. Durante mucho tiempo ese sitio fue un conjunto de endpoints REST, uno por producto y por tipo de gráfica: uno para las métricas de VPS, otro para el ancho de banda de VPS, otro para baremetal, otro para los sensores BMC, otro para los load balancers. Once en total, cada uno con sus propios parámetros y su propia forma de respuesta.

Funcionaba, hasta que dejó de hacerlo. Una página de proyecto con diez servidores, dos load balancers y un NAT gateway suponía decenas de peticiones solo para pintar las gráficas. Y quien quisiera los mismos números en sus propias herramientas tenía que aprenderse once endpoints ligeramente distintos.

Así que los sustituimos todos por uno. CubePath tiene ahora una API GraphQL en POST /graphql, y es la única vía por la que salen las métricas de la plataforma. La usa el panel, la usa la nueva página de Ancho de banda, y la puedes usar tú, con el mismo token de API que ya tienes.

Por Qué GraphQL, y Por Qué Solo para Métricas

Las métricas son el caso de libro para GraphQL. La pregunta casi nunca es "dame todo sobre este servidor". Es "dame la CPU de estos seis servidores en las últimas seis horas, la memoria de dos de ellos y el ancho de banda de este mes del load balancer que tienen delante". Con REST, eso son nueve peticiones y muchos datos que no has pedido. Con GraphQL, es una petición, y la respuesta tiene exactamente la forma de la pregunta.

{
  vpsList(projectId: "42") {
    name
    metrics(range: H6, metrics: [CPU_USAGE]) {
      series { name unit points { ts value } }
    }
  }
  loadBalancer(uuid: "...") {
    name
    bandwidthUsage { inBytes outBytes }
  }
}

Lo que deliberadamente no hace es cambiar nada. No hay mutaciones. Crear servidores, redimensionarlos o editar registros DNS sigue en la API REST, que es donde ya viven el log de actividad, las confirmaciones y la validación de cada escritura. Leer gráficas es un trabajo distinto a operar infraestructura, y mantenerlos separados significa que un token que le das a una máquina de monitorización nunca puede ser más que un token que lee gráficas.

Qué Incluye

La API cubre todos los productos que generan métricas:

  • VPS: CPU, memoria, lecturas y escrituras de disco, red de entrada y salida, y ancho de banda mensual, de un servidor o de hasta 200 a la vez
  • Availability groups: CPU media y memoria total de todo el grupo
  • Bare metal: tráfico y paquetes por segundo de los puertos del switch, ancho de banda mensual y de los últimos 30 días, y los sensores BMC: temperaturas, velocidad de ventiladores y estado de energía
  • Tránsito IP: tráfico y paquetes en tu puerto de tránsito
  • Load balancers: conexiones activas, conexiones nuevas por segundo, tráfico y ancho de banda mensual
  • NAT gateways: tráfico y ancho de banda mensual
  • Kubernetes: la salud del API server, cada nodo con sus condiciones (listo, presión de memoria, presión de disco), sus recursos y su uso, y las series del cluster en el tiempo
  • Ancho de banda: todos los servicios que mueven tráfico público, con su tráfico sumado por ubicación, producto, proyecto o servicio

Lo último es lo que alimenta la página de Ancho de banda que hemos lanzado esta semana, y es un buen ejemplo de lo que permite tener un solo endpoint. La página no es una funcionalidad especial del backend. Es una consulta GraphQL, y puedes lanzar exactamente la misma consulta tú.

Qué Puedes Construir con Ella

Lo interesante no es que el panel tenga gráficas. Es que ahora puedes tener los mismos datos donde quieras, sin hacer scraping de nada.

Tus propios dashboards. Si tu equipo ya vive en Grafana, el data source Infinity habla GraphQL. Apúntalo a https://api.cubepath.com/graphql con un token de solo lectura y tus servidores de CubePath quedan junto a todo lo demás que monitorizas. Cada serie vuelve con su unidad y con los timestamps alineados, así que CPU y memoria se pintan en el mismo eje sin código intermedio.

Un informe mensual de ancho de banda. bandwidthResources lista todos los servicios que mueven tráfico público con su proyecto, su ubicación y usage(month: "2026-09"), los bytes de entrada y salida de ese mes natural. Una sola petición te da el mes de cada servidor, load balancer y NAT gateway que tengas, listo para sumar por proyecto o por cliente. Lánzalo el día uno de cada mes y envíalo donde lea las cosas tu equipo de finanzas.

Comprobaciones de Kubernetes en CI. Antes de un despliegue, pregúntale al cluster si está sano:

{
  kubernetesCluster(uuid: "...") {
    health { up ready nodesReady nodesTotal podsPending serverCertExpires }
  }
}

Si nodesReady es menor que nodesTotal, o hay pods atascados en pending, el pipeline se para antes de empeorar las cosas. serverCertExpires te dice cuándo caduca el certificado del API server, que es justo lo que nadie recuerda hasta el día que pasa.

Hardware que no ves. La BMC de un servidor dedicado sabe cosas que el sistema operativo no sabe: la temperatura de entrada, la velocidad de los ventiladores, si la máquina está realmente encendida. baremetal { sensors { temperatures { name value unit } fans { name value unit } } } te da esas lecturas sin abrir una consola IPMI.

Decisiones de capacidad. "¿Qué servidores llevan una semana por debajo del 10% de CPU?" es un vpsList por proyecto con metrics(range: D7, metrics: [CPU_USAGE]). La respuesta es la lista de servidores que estás pagando y no usando.

Los Mismos Permisos que Todo lo Demás

No hay un sistema de permisos aparte para GraphQL. Acepta los mismos tokens que la API REST, y cada campo comprueba los mismos scopes: vps:read para VPS, baremetal:read para bare metal, kubernetes:read para clusters, y así con cada producto.

Eso tiene una consecuencia interesante. Una petición que pide métricas de VPS y salud de Kubernetes con un token que solo tiene vps:read no falla entera. Los campos de VPS vuelven, y el de Kubernetes vuelve como null con un error FORBIDDEN al lado. Recibes todo lo que el token puede ver, y una explicación clara del resto.

Los recursos de otras organizaciones se comportan exactamente igual que los que no existen: mismo NOT_FOUND, mismo mensaje. No hay forma de preguntarle a la API si un ID pertenece a otra persona.

Nuestra recomendación es la misma que para cualquier integración: crea un token solo con los scopes de lectura que necesita, fíjalo a la IP de la máquina que lo usa, y se convierte en una credencial que lee gráficas desde un sitio y nada más.

Se Degrada, No Se Rompe

Las métricas salen de un sistema distinto al resto de la plataforma, y cualquier sistema puede tener un mal minuto. Cuando pasa, la API no tira tu petición entera.

El servidor, el load balancer o el cluster se siguen resolviendo con su nombre y con los datos que no dependen de las métricas. Las series vuelven vacías, y un error con el código METRICS_UNAVAILABLE señala exactamente qué campos se han visto afectados. Un dashboard puede mostrar "métricas no disponibles temporalmente" en una gráfica en lugar de una página en blanco.

Cada error lleva un código (UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, BAD_USER_INPUT, METRICS_UNAVAILABLE, QUERY_TOO_COMPLEX), así que tu código puede decidir según algo estable en lugar de interpretar mensajes.

Límites Pensados para Consultar a Menudo

El panel refresca las gráficas cada pocos segundos en modo en vivo, así que la API se diseñó para polling desde el principio. El límite es de 600 peticiones por minuto por token, y cada petición cuenta una vez pida lo que pida.

Lo que acota una petición es cuántos datos devuelve: hasta unos 24.000 puntos, que son 200 series de una hora u 80 de treinta días. Una consulta que pide más se rechaza antes de ejecutarse, con QUERY_TOO_COMPLEX, en lugar de ejecutarse a medias. Los rangos largos se submuestrean solos, así que una gráfica de 30 días tiene unos 300 puntos, no 86.000.

Dónde Encaja

GraphQL no sustituye a la API REST, ni lo pretende. REST sigue siendo donde creas, cambias y borras cosas, y el servidor MCP sigue siendo la forma de dejar que un asistente de IA opere tu infraestructura.

Lo que GraphQL sustituye es cualquier sitio donde pintabas gráficas o montabas informes con datos de CubePath: once endpoints se han convertido en uno, y las gráficas del panel en algo que puedes reproducir exactamente en tus propias herramientas.

La guía de la API GraphQL tiene la lista completa de campos, los errores y los límites. Crea un token de solo lectura, envía tu primera consulta y lleva los números de tu infraestructura a donde de verdad los miras.