Gestión mediante la API HTTP

Todo lo que hace la interfaz web, el nodo sabe hacerlo por una petición desde fuera: la API HTTP lee y modifica la configuración del servicio en funcionamiento y devuelve su estado. Junto con la interfaz web son las únicas interfaces que aplican un cambio de inmediato e informan del resultado.

La página ofrece una visión general: dónde está la API, cómo está organizada, cómo llegan los errores y en qué se diferencia de editar el archivo de configuración. La referencia de cada petición y de cada clave está en documentos aparte (Documentos de referencia); aquí no se repite.

Acceso

La API responde en el mismo servidor web que la interfaz de administración. En la configuración suministrada es el puerto 8808; si en los ajustes no hay ningún puerto indicado, el servicio usa el valor integrado 43971. El puerto TLS es 43981, pero justo después de la instalación TLS está desactivado y ese puerto no se escucha (Configuración inicial). La API no tiene una dirección ni un prefijo propio del tipo /api.

• HTTP y HTTPS están en igualdad. La redirección del puerto abierto a TLS solo afecta a las páginas de la interfaz; las peticiones de la API siguen funcionando por ambos protocolos.

• La autenticación es HTTP Digest, con las mismas cuentas que la interfaz web y los mismos roles: Admin — acceso completo, Restricted admin — leerlo todo y poner en pausa un flujo, su entrada o su salida, Viewer — solo lectura. Una escritura realizada fuera del propio rol se rechaza. En lugar de la contraseña, la sesión se puede presentar con una clave de inicio automático: una cookie, la cabecera X-Auth-Token o el parámetro ?auth-token=.

• Las peticiones desde el propio nodo no se autentican. Una llamada llegada por la interfaz de bucle (127.0.0.1, ::1) pasa sin Digest y recibe el rol Admin. Esto no se puede desactivar: no hay ningún ajuste para ello. La concesión sí tiene límites: no se puede reclamar desde fuera del nodo —atribuirse una dirección de bucle mediante una cabecera no funciona— y se retira para una petición entre orígenes, pues de lo contrario una página web abierta en el nodo gobernaría toda la API a través de 127.0.0.1 sin credencial alguna.

  Hay una sola consecuencia ante la que actuar: cualquier proceso del nodo dispone de la configuración sin contraseña. Si se pone un proxy inverso delante de la API, diríjalo a una dirección no de bucle del mismo nodo; entonces la autenticación funciona con normalidad. Un proxy que se dirige a 127.0.0.1 reparte acceso completo a todos aquellos cuyas peticiones retransmite.

• Solo hay dos métodos — GET y POST. A cualquier otro método llega la respuesta «método no admitido»; la excepción es la petición previa OPTIONS del navegador, a la que el servidor responde con un permiso si el origen de la petición está admitido.

Advertencia

El rol restringe únicamente la escritura. La comprobación del rol se realiza para las peticiones POST; la lectura no está restringida en absoluto, y los valores se devuelven tal cual, sin enmascarar. Una cuenta con el rol Viewer ve todas las contraseñas, los secretos de Meshwork, las frases de contraseña de los transportes y las claves de protección de contenidos; y exportar una copia de seguridad de los ajustes también es una lectura, es decir, toda la configuración en una sola petición. El rol Viewer limita la posibilidad de cambiar el nodo, no el acceso a sus secretos: créelo sabiéndolo.

La difusión de los flujos y de la guía de programas funciona en puertos propios y no gestiona los ajustes (Configuración inicial).

De qué se compone la API

Familia	Función
/config/…	Lectura y modificación de la configuración. El árbol de peticiones repite en lo esencial la estructura del archivo de configuración: una sección del archivo es un nodo del árbol (Estructura del documento). Hay divergencias: la matriz de almacenes de archivo se direcciona como /config/dvr-storage y los conjuntos de canales de la guía de programas como /config/epg-channel-set, aunque en el archivo están dentro de dvr-storage-list y de epg-server.
/data/…	El estado del servicio en funcionamiento, sobre todo para lectura: los flujos y sus cadenas, el equipamiento, la guía de programas, el monitor del sistema, el registro, la información de la licencia. Unas pocas peticiones cambian el estado —restablecer las estadísticas, iniciar un escaneo, retirar una alerta—; de ellas solo una modifica la configuración: sacar a un par Meshwork de la vista general del dominio. Hay ejemplos de peticiones listos en Programación diaria en JSON y Asistente de reclamaciones.
/schema/…	Listas de referencia en formato JSON, solo de lectura: los tipos de entrada y de salida que admite esta compilación, los idiomas, las tarjetas de recepción y los dispositivos de transcodificación encontrados, la escala de importancia y los códigos de alarma. No tienen relación con el archivo de esquema de los ajustes (Comprobación con el JSON Schema).
Direcciones sueltas	Unas pocas peticiones de servicio fuera de estos árboles: reiniciar el servicio, exportar y restaurar una copia de seguridad de los ajustes, la lista de interfaces de red, cerrar la sesión.

Cómo llegan los errores

Un error de nivel de aplicación lo devuelve la API con código HTTP 200 y un campo result distinto de cero en el cuerpo de la respuesta: un valor fuera de rango, una comprobación rechazada, un intento de escribir una clave inmutable, la negativa a escribir una clave inaccesible para ese rol.

Un script que solo comprueba el código HTTP contará, por tanto, como exitosos todos esos rechazos uno tras otro. Analice el cuerpo de la respuesta.

También aparecen códigos distintos de 200, pero significan otra cosa: 401 — no se ha superado la autenticación, 403 — el rol no está admitido a la petición en sí, 404 — no existe tal petición, 405 — el método no está admitido. Así pues, un rechazo por rol llega de dos maneras distintas: la petición entera se rechaza con el código 403, mientras que una clave concreta no admitida vuelve en una respuesta corriente con un result distinto de cero.

Un valor fuera del rango permitido la API lo rechaza. En eso se diferencia de la lectura del archivo de configuración, donde ese valor se lleva al límite del rango (Se acepta, pero no como pretendía quien editó).

Una clave desconocida la API no la rechaza: se omite exactamente igual que al leer el archivo, la respuesta llega con result 0 y el único rastro queda en el registro del nodo. Por eso una errata en el nombre de una clave tampoco se ve aquí: los nombres de las claves se comprueban de antemano con el esquema (Comprobación con el JSON Schema).

Cambios que necesitan un reinicio

Dos cambios surten efecto solo tras reiniciar el servicio: la activación de la licencia y la restauración de los ajustes desde una copia de seguridad. Ninguno de los dos deja el reinicio a criterio del operador: una vez aceptado el archivo, el servicio se reinicia solo al cabo de unos cuatro segundos —no se puede aplazar— y durante el reinicio el nodo no está disponible. Las respuestas de estas dos peticiones no llevan el campo reboot; en las respuestas JSON de la API de configuración ese campo significa que el nodo ya se va a reiniciar, no que el reinicio esté esperando una orden. Del mismo modo, por sí solo, se reinicia el nodo cuya licencia ha caducado. Reiniciar el servicio por voluntad propia se puede con una petición aparte, desde la interfaz web o con el comando sudo systemctl restart pss.

Cambiar los puertos de escucha y activar TLS no exigen reiniciar el servicio: cierra el socket de escucha y lo vuelve a abrir, y en la respuesta no habrá campo reboot. Las conexiones abiertas en ese puerto se cortan al hacerlo, y a partir de entonces hay que conectarse ya al nuevo puerto.

La API o el archivo de configuración

	HTTP API	El archivo pss.json
Cuándo surte efecto	De inmediato	Desde el siguiente arranque del servicio
Estado del servicio	En funcionamiento	Detenido
Resultado	Se devuelve en la respuesta	Visible solo en el registro tras el arranque
Valor fuera de rango	Se rechaza	Se lleva al límite
Clave desconocida	Se ignora en silencio, result 0	Se ignora en silencio, salvo que se lea el registro
Para qué resulta cómodo	Cambios puntuales, automatización, observación	Ediciones masivas, traslado de los ajustes entre nodos y versiones

Editar el archivo de un servicio en funcionamiento es inútil y peligroso: el servicio sobrescribe pss.json con lo que mantiene en memoria, y lo hace según su propio calendario; la edición desaparecerá sin un solo mensaje. Detenga el servicio y compruebe el archivo con el esquema antes de arrancarlo; el procedimiento está en Editar, comprobar y trasladar los ajustes.

Documentos de referencia

Documento	Contenido
http_config_api.txt	La referencia de la API de configuración: el protocolo, las operaciones, el árbol /config y la descripción punto por punto de cada clave: tipo, restricciones, valor por defecto.
http_data_api.txt	La referencia de la API de estado y estadísticas: el árbol /data, los formatos de respuesta, las peticiones al registro y a las bases.
pss_config_file.txt	La referencia del formato del archivo de configuración. Su exposición para el operador es El archivo de configuración pss.json.
pss_config_editing.txt	Los procedimientos de edición, comprobación y traslado de los ajustes. Su exposición es Editar, comprobar y trasladar los ajustes.
pss.schema.json, pss.compat.schema.json	Una descripción legible por máquina del archivo de configuración en formato JSON Schema (Comprobación con el JSON Schema).

Los documentos están escritos en inglés. No forman parte del paquete: no están en el nodo y no hace falta buscarlos allí.

Todo ello está publicado en el sitio de la documentación, con un directorio por cada versión del producto:

https://doc2.pstreamer.tv/reference/      cuatro documentos de referencia
https://doc2.pstreamer.tv/schema/         dos esquemas

Tome el directorio de la versión que tiene instalada: la referencia de otra edición no describe su nodo.

Advertencia

No se garantiza la compatibilidad hacia atrás. Con una actualización pueden cambiar tanto la API HTTP como el esquema y el formato del archivo de configuración: la composición y los nombres de las claves, los rangos de valores, la forma de las peticiones y de las respuestas. Vuelva a comprobar los scripts que trabajan con la API después de cada actualización, y tome los documentos de referencia y el esquema de la misma versión que la compilación instalada.

De ello se derivan tres reglas para quien escribe su propia integración:

• Fíjese a la versión para la que está escrito el script, y compruébela al arrancar.

• Lea de vuelta después de escribir. Una clave que ya no existe en la nueva compilación no se rechaza, sino que se ignora, y la respuesta informa de éxito: la única petición que habría detectado esa desaparición es la que no la detecta.

• Un atributo ausente en la respuesta significa «esta versión no lo comunica», y no cero. De lo contrario, un indicador retirado o renombrado en una actualización se convierte en una medición verosímil de algo que no existe.