¶ Definición de la API REST para OpenGnSys
¶ Motivación
Se desarrolla una API para conexión REST con acceso mediante HTTPS que se incluye a partir de la versión 1.1 de OpenGnSys, con la intención de implementar su integración con el broker de acceso remoto UDS Enterprise, como base principal para implantar el Proyecto Remote PC.
¶ Generalidades de la API REST
¶ Métodos HTTP en REST
Equivalencia entre métodos (verbos) HTTP y operaciones REST ejecutadas sobre los recursos.
| GET | consulta/lectura de sus datos |
|---|---|
| PUT | actualización completa de datos |
| PATCH | actualización parcial de datos |
| POST | creación de un nuevo recurso |
| DELETE | borrado del recurso |
¶ Acceso autentificado a la API
El acceso al API REST de OpenGnSys debe estar autentificado por una clave aleatoria que se generará automáticamente a la hora de iniciar un servicio o se asociará a los usuarios con acceso al servidor.
La aplicación que acceda al API REST debe usar una petición POST a una URL de conexión donde incluya los datos de usuario y clave y que devuelva la clave de acceso a la API. El resto de conexiones REST deberá usar una cabecera HTTP Authentication con el contenido de dicha clave.
¶ Consultas REST
Las rutas definidas usarán verbos GET para obtener información de recursos y POST para enviar datos al servidor y para actualización de los recursos (no se prevé inicialmente el uso de los verbos PUT, PATCH ni DELETE).
Las llamadas a rutas GET pueden tener parámetros que irán incluidos dentro de la URL.
Las llamadas a rutas POST incluirán sus parámetros en formato JSON.
¶ Respuestas REST
Las respuestas REST estarán compuestas de los siguientes datos:
- Código de estado HTTP.
- Datos en formato JSON.
Los códigos de estado HTTP definidos son:
| 200 | Operación correcta |
|---|---|
| 400 | faltan datos de acceso o parámetro incorrecto |
| 401 | login incorrecto o no hay acceso a un recurso |
| 404 | recurso no encontrado |
| 500 | error genérico o no hay conexión con el servidor |
¶ Rutas definidas en OpenGnsys Server
La API REST del servidor OpenGnsys estará bajo la URL https://Servidor/opengnsys/rest.
Nota: Las rutas que se indican son relativas a la URL de la API REST y los identificadores variables se preceden del carácter ":".
¶ Rutas generales
/login
- Autenticación de usuario.
- Método: POST.
- Parámetros:
username(cadena): nombre de usuario.password(cadena): contraseña.
- Devuelve: objeto.
userid(entero): identificador del usuario.apikey(cadena): clave de acceso a la API REST.
/info
- Muestra información general del sistema.
- Método: GET.
- Devuelve: objeto.
project(cadena): nombre del proyecto (OpenGnsys).version(cadena): versión instalada.release(cadena): revisión instalada.services(array de cadenas): lista de servicios iniciados ("server","repository","tracker").oglive(array de objetos): datos de los clientes ogLive instalados.distribution(cadena): distribución Linux del cliente ogLive.kernel(cadena): versión del Kernel Linux.architecture(cadena): arquitectura del Kernel ("i386"oamd64).revision(cadena): revisión del cliente ogLive.directory(cadena): subdirectorio de instalación.iso(cadena): fichero de imagen ISO con el cliente ogLive descargado.
/status
- Muestra información del estado actual del servidor.
- Método: GET.
- Devuelve: objeto.
memInfo(objeto): datos de memoria del servidor.total(cadena): cantidad total de memoria.used(cadena): cantidad de memoria usada por los procesos en ejecución.
cpu(objeto): datos de procesadores del servidor.model(cadena): modelo del procesado.usage(cadena): porcentaje de uso.
/ous
- Listar Unidades Organizativas accesibles por el usuario.
- Método: GET.
- Devuelve: array de objetos.
id(entero): identificador de la UO.name(cadena): nombre de la UO.
/ous/:id1
- Obtener los datos de la UO con identificador id1.
- Método: GET.
- Devuelve: objeto
id(entero): identificador de la UO.name(cadena): nombre de la UO.description(cadena): descripción de la UO.
/ous/:id1/groups
(pendiente de documentar)
/ous/:id1/labs
- Listar las aulas definidas en la UO id1.
- Método: GET.
- Devuelve: array de objetos.
id(entero): identificador del aula.name(cadena): nombre del aula.inremotepc(booleano): indica si los recursos del aula están disponibles para el Proyecto Remote PC.group(objeto): grupo al que pertenece el aula.id(entero): identificador del grupo.
ou(objeto): UO a la que pertenece el aula.id(entero): identificador de la UO.
/ous/:id1/labs/:id2
- Obtener los datos del aula con identificador id2 de la UO id1.
- Método: GET.
- Devuelve: objeto.
id(entero): identificador del aula.name(cadena): nombre del aula.location(cadena): datos de localización del aula.description(cadena): descripción del aula.inremotepc(booleano): indica si los recursos del aula están disponibles para el Proyecto Remote PC.capacity(entero): aforo del aula.defclients(entero): nº de clientes definidos en el aula.projector(booleano): indica si el aula dispone o no de proyector.board(booleano): indica si el aula dispone o no de pizarra electrónica.routerip(cadena): dirección IP del router del aula.netmask(cadena): dirección IP de la máscara de red común a los clinetes del aula.ntp(cadena): dirección IP del servidor NTP del aula.dns(cadena): dirección IP del servidor DNS principal para el aula.proxyurl(cadena): URL del servidor proxy del aula.mcastmode(cadena): tipo de conexión Multicast ("full-duplex"o"half-duplex").mcastip(cadena): dirección IP para comunicaciones Multicast entre clientes del aula.mcastport(entero): puerto para comunicaciones Multicast.mcastspeed(entero): velocidad máxima de las comunicaciones Multicast (en Mbps).p2pmode(cadena): tipo de conexión P2P ("peer","leecher"o"seeder").p2ptime(entero): tiempo de conexión tras finalizar la recepción P2P (en s.).picture(cadena): fichero con foto del aula.
/ous/:id1/labs/:id2/clients
- Listar los clientes definidos en el aula id2 de la UO id1.
- Método: GET.
- Devuelve: array de objetos.
id(entero): identificador del cliente.name(cadena): nombre del cliente.mac(cadena): dirección MAC de la interfaz de red (sin caracteres "
.ip(cadena): dirección IP del cliente.ou(objeto): OU a la que pertenecen.id(entero): identificador de la UO.
lab(objeto): aula a la que pertenecen.id(entero): identificador de la UO.
/ous/:id1/labs/:id2/clients/status
- Obtener el estado de ejecución de todos los clientes del aula id2 de la UO id1.
- Método: GET.
- Devuelve: array de objetos.
id(entero): identificador del cliente.ip(cadena): dirección IP del cliente.status(cadena): estado de inicio del cliente ("off","oglive","busy","linux","windows","macos"o"unknown").loggedin(booleano, opcional): indica si un usuario tiene una sesión abierta en un sistema operativo (solo si usa OGAgent).
/ous/:id1/labs/:id2/clients/:id3
- Obtener los datos del cliente con identificador id3 del aula id2 de la UO id1.
- Método: GET.
- Devuelve: objeto.
id(entero): identificador del cliente.name(cadena): nombre del cliente.serialno(cadena): nº de serie del cliente.netiface(cadena): interfaz de red por defecto.netdriver(cadena): driver (módulo a cargar) del interfaz de red (si"generic", no se necesita cargar nada).mac(cadena): dirección MAC de la interfaz de red (sin caracteres ".ip(cadena): dirección IP del cliente.netmask(cadena): máscara de red.routerip(cadena): dirección IP del router por defecto.repo(objeto): repositorio de imágenes.id(entero): identificador del repositorio.
validation(booleano): indica si se necesita autenticación para entrar en el menú del cliente.boottype(cadena): plantilla asociada para el arranque del equipo.picture(cadena): fichero con foto del cliente.
/ous/:id1/labs/:id2/clients/:id3/hardware
- Obtener los datos del perfil de hardware con la lista de dispoistivos del cliente con identificador id3 del aula id2 de la UO id1.
- Método: GET.
- Devuelve: objeto.
id(entero): identificador del cliente.name(cadena): nombre del cliente.hardware(array de objetos): datos de los componentes hardware.type(cadena): tipo de componente, los valores se corresponden con el camponemonicode la tablatipohardwares.description(cadena): descripción del componente.
/ous/:id1/labs/:id2/clients/:id3/diskcfg
- Obtener los datos de configuración e instalación de discos del cliente con identificador id3 del aula
- Método: GET.
- Devuelve: objeto.
id(entero): identificador del cliente.name(cadena): nombre del cliente.diskcfg(array de objetos): configuración de discos.- Configuración para discos:
disk(entero): nº de orden del disco.parttable(cadena): tipo de tabla de particiones ("MSDOS","GPT","LVM"o"ZPOOL").size(entero): tamaño del disco (en KB).
- Configuración para particiones (puede estudiarse si es mejor que esta información sea una array
partitionsdentro de la configuración del disco):disk(entero): nº de orden del disco.partition(entero): nº de orden de la partición.parttype(cadena): nemónico del tipo de partición.size(entero): tamaño de la partición (en KB).filesystem(cadena): nemónico del tipo de sistema de ficheros.usage(entero): porcentaje de uso del sistema operativo.os(cadena, opcional): sistema operativo instalado.image(objeto, opcional): datos de la imagen desplegada.id(cadena): identificador de la imagen.deploydate(cadena): fecha y hora de despliegue de la imagen (formato AAAA-MM-DD HH:MM:SS).updated(booleano): indica si la imagen desplegada está actualizada a la última versión del repositorio.
- Configuración para discos:
/ous/:id1/labs/:id2/clients/:id3/status
- Obtener el estado de inicio del cliente con identificador id3 del aula
- Método: GET.
- Devuelve: objeto.
id(entero): identificador del cliente.ip(cadena): dirección IP del cliente.status(cadena): estado de inicio del cliente ("off","oglive","busy","linux","windows","macos"o"unknown").loggedin(booleano, opcional): indica si un usuario tiene una sesión abierta en un sistema operativo (solo si usa OGAgent).
/ous/:id1/repos
- Listar los repositorios de imágenes definidos en la UO id1.
- Método: GET.
- Devuelve: array de objetos.
id(entero): identificador del repositorio.name(cadena): nombre del repositorio.ou(objeto): UO a la que pertenece.id(entero): identificador de la UO.
/ous/:id1/repos/:id2
- Obtener los datos del repositorio con identificador id2 de la UO id1.
- Método: GET.
- Devuelve: objeto.
id(entero): identificador del repositorio.name(cadena): nombre del repositorio.description(cadena): descripción del repositorio.ip(cadena): dirección IP del repositorio.
/ous/:id1/images
- Listar las imágenes almacenadas en los repositorios definidos en la UO id1.
- Método: GET.
- Devuelve: array de objetos.
id(entero): identificador de la imagen.name(cadena): nombre de la imagen.inremotepc(booleano): indica si la imagen está preparada para ser usada en el Proyecto Remote PC.ou(objeto): UO a la que pertenece.id(entero): identificador de la UO.
/ous/:id1/images/:id2
- Obtener los datos de la imagen con identificador id2 de la UO id1.
- Método: GET.
- Devuelve: objeto.
- Datos generales:
id(entero): identificador de la imagen.name(cadena): nombre de la imagen (nombre del fichero de imagen sin extensión).description(cadena): descripción de la imagen.comments(cadena): comentarios acerca de de la imagen.inremotepc(booleano): indica si la imagen está preparada para ser usada en el Proyecto Remote PC.repo(objeto): repositorio donde está almacenada.id(entero): identificador del repositorio.
type(cadena): tipo de imagen ("monolithic","base"o"incremental").
- Datos incluidos si la imagen es de tipo incremental:
baseimg(cadena): nombre de la imagen base.
- Datos incluidos si la imagen ha sido generada en el cliente modelo:
client(objeto): datos del cliente modelo.id(entero): identificador del cliente.disk(entero): nº de orden del disco.partition(entero): nº de orden de la partición.
creationdate(cadena): fecha y hora de creación de la imagen (formato AAAA-MM-DD HH:MM:SS).release(entero): nº de revisión de la imagen.
- Datos generales:
/ous/:id1/images/:id2/software
- Obtener los datos del perfil de software con la lista de aplicaciones instaladas en la imagen con identificador id2 de la UO id1.
- Método: GET.
- Devuelve: objeto
id(entero): identificador de la imagen.name(cadena): nombre de la imagen.os(cadena): sistema operativo instalado.software(array de objetos): datos de las aplicaciones instaladas.application(cadena): nombre y versión de la aplicación o del paquete del sistema operativo.
¶ Rutas para OGAgent
Rutas que atienden las notificaciones push de agentes OGAgent:
/ogagent/started
- Notificación de que se ha iniciado el servicio OGAgent en un cliente.
- Método: POST.
- Parámetros:
ip(cadena): dirección IP del cliente.mac(cadena): dirección MAC de la interfaz de red.ostype(cadena): tipo de sistema operativo instalado.osversion(cadena): versión de sistema operativo instalado.secret(cadena): clave de acceso a la API REST de OGAgent (generada aleatoriamente al iniciar el servicio).
/ogagent/stopped
- Notificación de que se ha detenido el servicio OGAgent en un cliente.
- Método: POST.
- Parámetros:
ip(cadena): dirección IP del cliente.mac(cadena): dirección MAC de la interfaz de red.ostype(cadena): tipo de sistema operativo.osversion(cadena): versión de sistema operativo.
/ogagent/loggedin
- Notificación de que un usuario ha iniciado una sesión de escritorio en un cliente.
- Método: POST.
- Parámetros:
ip(cadena): dirección IP del cliente.user(cadena): usuario que inicia la sesión.language(cadena): código del idioma de la sesión.ostype(cadena): tipo de sistema operativo.osversion(cadena): versión de sistema operativo.
/ogagent/loggedout
- Notificación de que un usuario ha finalizado una sesión de escritorio en un cliente.
- Método: POST.
- Parámetros:
ip(cadena): dirección IP del cliente.user(cadena): usuario que cierra la sesión.ostype(cadena): tipo de sistema operativo.osversion(cadena): versión de sistema operativo.
¶ Rutas para Remote PC
Las siguientes rutas REST serán utilizadas por un servidor UDS para controlar procesos de iniciación y parada de clientes que tengan instalada una imagen en particular. El servidor OpenGnsys actuará como intermediario entre el servidor de UDS y los agentes OGAgent instalados en los sistemas operativos que podrán usarse en remoto.
/ous/:id1/images/:id2/reserve
- Elegir al azar un cliente que tenga instalada una imagen (y, opcionalmente, que esté situado en una determinada aula), reservar su uso para acceso remoto durante un número de horas (24 h. por defecto), enviarle una operación de arranque Wake-On-Lan (o de reinicio, si el cliente está encendido) y registrar en su cola de acciones la operación de iniciar sesión en la partición de dicha imagen.
- Método: POST.
- Parámetros (objeto):
labid(entero): identificador del aula del cliente (opcional).maxtime(entero): tiempo máximo de reserva, en horas (opcional, 24 h. por defecto).
- Devuelve: objeto
id(entero): identificador del cliente seleccionado.name(cadena): nombre del cliente.mac(cadena): dirección MAC de la interfaz de red (sin caracteres ":" ).ip(cadena): dirección IP del cliente.ou(objeto): OU a la que pertenecen.id(entero): identificador de la UO.
lab(objeto): aula a la que pertenecen.id(entero): identificador de la UO.
/ous/:id1/labs/:labid/clients/:clntid/events
- Registrar URLs para redirigir a un servidor UDS aquellas notificaciones push enviadas por un agente OGAgent de un cliente reservado para acceso remoto.
- Método: POST.
- Parámetros:
urlLogin(cadena): URL para redirigir una notificación de inicio de sesión de usuario.urlLogout(cadena): URL para redirigir una notificación de fin de sesión de usuario.
/ous/:id1/labs/:labid/clients/:clntid/session
- Registrar parámetros específicos de la sesión del usuario enviados por un servidor UDS.
- Método: POST.
- Parámetros:
deadLine(cadena): tiempo restante para apagar el cliente (en segundos).
/ous/:id1/labs/:labid/clients/:clntid/unreserve
- Liberar un cliente marcado para acceso remoto, borrando sus datos de registro y enviando una operación de apagado.
- Método: DELETE.
Notas de implementación:
- Se ha creado un proceso de revisión cronológica de ejecución de acciones.
- Sería recomendable modificar el proceso de restauración para incluir en el SO datos de la imagen desplegada.
- Estudiar la manera de reintentar el envío de peticiones fallidas.
¶ Rutas definidas en OpenGnsys Repository
La API REST de un repositorio OpenGnsys estará bajo la URL https://Repositorio/opengnsys/rest.
/repository/images
- Devuelve información sobre las imágenes almacenadas en el repositorio.
- Método: GET.
- Devuelve: objeto
directory(caena): directorio del repositorio.images(array de objetos): datos de imágenes globales.name(cadena): nombre de la imagen.type(cadena): tipo de imagen (dirpara directorio o extensión del fichero).clientname(cadena): nombre del cleinte modelo donde se generó la imagen.clonator(cadena): programa de clonación.compressor(cadena): programa de compresión.filesystem(cadena): tipo de sistema de archivos.datasize(entero): tamaño ocupado por los datos (en bytes).size(entero): tamaño del fichero de imagen (en bytes).modified(fecha-hora): fecha de modificación del fichero de imagen.mode(cadena): permisos del fichero de imagen (4 digitos octales).backedup(booleano): indicador de si existe copia de seguridad de la imagen.backupsize(entero): tamaño del fichero de copia de seguridad (en bytes).
ous(array de objetos): datos de imágenes en subdirectorios de unidades organizativas.subdir(cadena): subdirectorio de la unidad organizativa.images(array de objetos): datos de imágenes para la unidad organizativa.name(cadena): nombre de la imagen.type(cadena): tipo de imagen (dirpara directorio o extensión del fichero).clientname(cadena): nombre del cleinte modelo donde se generó la imagen.clonator(cadena): programa de clonación.compressor(cadena): programa de compresión.filesystem(cadena): tipo de sistema de archivos.datasize(entero): tamaño ocupado por los datos (en bytes).size(entero): tamaño del fichero de imagen (en bytes).modified(fecha-hora): fecha de modificación del fichero de imagen.mode(cadena): permisos del fichero de imagen (4 digitos octales).backedup(booleano): indicador de si existe copia de seguridad de la imagen.backupsize(entero): tamaño del fichero de copia de seguridad (en bytes).
disk(objeto): datos generales del repositorio.total(entero): tamaño total del disco (en bytes).free(entero): espacio libre del disco (en bytes).
/repository/image/:imagename
/repository/image/:ouname/:imagename
- Obtener los datos de una imagen almacenada en el repositorio (tanto general como alojada en un subdirectorio de una unidad organizativa).
- Método: GET.
- Devuelve: objeto
name(cadena): nombre de la imagen.type(cadena): tipo de imagen (dirpara directorio o extensión del fichero).clientname(cadena): nombre del cleinte modelo donde se generó la imagen.clonator(cadena): programa de clonación.compressor(cadena): programa de compresión.filesystem(cadena): tipo de sistema de archivos.datasize(entero): tamaño ocupado por los datos (en bytes).size(entero): tamaño del fichero de imagen (en bytes).modified(fecha-hora): fecha de modificación del fichero de imagen.mode(cadena): permisos del fichero de imagen (4 digitos octales).backedup(booleano): indicador de si existe copia de seguridad de la imagen.backupsize(entero): tamaño del fichero de copia de seguridad (en bytes).
/repository/poweron
- Realiza una solicitud de arranque por Wake-On-Lan a equipos usando las direcciones MAC (Ethernet).
- Método: POST.
- Parámetros:
macs(array de cadenas): direcciones MAC.
- Devuelve: objeto
message(cadena): salida de ejecución.
¶ Rutas definidas en OGAgent
La API REST de un agente OpenGnsys para sistemas operativos estará bajo la URL https://Cliente:8000/opengnsys.
/logoff
- Lanzar un proceso para cerrar la sesión del usuario matando todos sus procesos.
- Método: GET.
- Devuelve: objeto
op(cadena): operación lanzada (launched).
/popup
- Lanzar un proceso para mostrar una ventana emergente con un mensaje en la sesión del usuario activo (la ventana se mostrará como mucho durante 1 minuto).
- Método: POST.
- Parámetros:
title(cadena): título de la cabecera de la ventana.message(cadena): mensaje a mostrar.
- Devuelve: objeto
op(cadena): operación lanzada (launched).
/poweroff
- Lanzar un subproceso para apagar el sistema.
- Método: GET.
- Devuelve: objeto
op(cadena): operación lanzada (launched).
/reboot
- Lanzar un subproceso para reiniciar el sistema.
- Método: GET.
- Devuelve: objeto
op(cadena): operación lanzada (launched).
/script
- Lanzar un subproceso para ejecutar un script en el cliente (codificado en Base64).
- Método: POST.
- Parámetros:
script(cadena): código del script codificado en Base64.client(booleano): indica si el script se ejecuta en la sesión del usuario (true) o como administrador del sistema (false).
- Devuelve: objeto
op(cadena): operación lanzada (launched).
/status
- Muestra el estado actual del sistema.
- Método: GET.
- Devuelve: objeto
status(cadena): estado (LNXpara SO Linux,WINpara Windows,OSXpara macOS X).loggedin(booleano): indicca si hay iniciada una sesión de usuario.