wiki:ApiRest

Version 5 (modified by ramon, 9 years ago) (diff)

Completar documentación de la API REST actual.

TOC(heading=Índice)?

Propuesta de API REST para debatir en el grupo de desarrollo.

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.

Acceso autentificado a la API

El acceso al API REST de OpenGnSys debe estar autentificado por una clave aleatoria que se asociada a aquellos 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.

Rutas de la API REST

La API REST estará bajo la URL https://Servidor/opengnsys/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

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 "parámetro=valor".

Respuestas REST

Las respuestas REST estarán compuestas de los siguientes datos:

  • Código de estado HTTP.
  • Datos en formato JSON, que incluirá al menos, los parámetros:
    • error (booleano): indicando el éxito (false) o fallo (true) de la operación.
    • Párametros de salida de la operación (si "error":false).
    • message (cadena): descripción del error (si "error":true).

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
500 error genérico o no hay conexión con el servidor

Rutas definidas

Nota: Las rutas que se indican son relativas a la URL de la API REST y los identificadores variables se preceden del carácter ":".

  • /login
    • Autenticación de usuario.
    • Método: POST.
    • Parámetros:
      • username (cadena): nombre de usuario.
      • password (cadena): contraseña.
    • Devuelve:
      • userid (entero): identificador del usuario.
      • apikey (cadena): clave de acceso a la API REST.
  • /ous
    • Listar Unidades Organizativas accesibles por el usuario.
    • Método: GET.
    • Deveulve:
      • ous (array): datos de las Unidades Organizativas definidas, compuesta por:
        • ouid (entero): identificador de la UO.
        • ouname (cadena): nombre de la UO.
  • /ous/:id1
    • Obtener los datos de la UO con identificador id1.
    • Método: GET.
    • Devuelve:
      • ouid (entero): identificador de la UO.
      • ouname (cadena): nombre de la UO.
      • description (cadena): descripción de la UO.
  • /ous/:id1/rooms
    • Listar las aulas definidas en la UO id1.
    • Método: GET.
    • Deveulve:
      • ouid (entero): identificador de la UO.
      • rooms (array): datos de las aulas definidas, compuesta por:
        • roomid (entero): identificador del aula.
        • roomname (cadena): nombre del aula.
  • /ous/:id1/rooms/:id2
    • Obtener los datos del aula con identificador id2 de la UO id1.
    • Método: GET.
    • Devuelve:
      • roomid (entero): identificador del aula.
      • roomname (cadena): nombre del aula.
      • description (cadena): descripción del aula.
      • inremotepc (booleano): indica si los recursos del aula están disponible para el Proyecto Remote PC.
      • maxclients (entero): nº máximo de clientes 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.
      • 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.).
  • /ous/:id1/rooms/:id2/clients
    • Listar los clientes definidos en el aula id2 de la UO id1.
    • Método: GET.
    • Devuelve:
      • ouid (entero): identificador de la UO.
      • roomid (entero): identificador del aula.
      • clients (array): datos de los clientes definidas, compuesta por:
        • clientid (entero): identificador del cliente.
        • clientname (cadena): nombre del cliente.
  • /ous/:id1/rooms/:id2/clients/:id3
    • Obtener los datos del cliente con identificador id3 del aula id2 de la UO id1.
    • Método: GET.
    • Devuelve:
      • clientid (entero): identificador del cliente.
      • clientname (cadena): nombre 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).
      • macaddress (cadena): dirección MAC de la interfaz de red (sin caracteres ":").
      • ipaddress (cadena): dirección IP del cliente.
      • netmask (cadena): máscara de red.
      • routerip (cadena): dirección IP del router por defecto.
      • repoid (cadena): identificador del repositorio de imágenes.
      • boottype (cadena): plantilla asociada para el arranque del equipo.
    • Otros datos que pueden incluirse:
      • hardprofid (entero): identificador del perfil de hardware del cliente.
      • menuid (entero): identificador del menú de inicio del cliente.
      • validation (booleano): indica si se necesita autenticación para entrar en el menú del cliente.
  • /ous/:id1/rooms/: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:
      • clientid (entero): identificador del cliente.
      • clientname (cadena): nombre del cliente.
      • hardware (array): datos de los componentes hardware, compuesta por:
        • type (cadena): tipo de componente, los valores se corresponden con el campo nemonico de la tabla tipohardwares.
        • description (cadena): descripción del componente.
  • /ous/:id1/rooms/: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:
      • clientid (entero): identificador del cliente.
      • clientname (cadena): nombre del cliente.
      • diskcfg (array): configuración de discos, compuesta por:
        • 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 partitions dentro de la configuración 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.
          • os (cadena): sistema operativo instalado.
          • idimage (cadena): identificador de la imagen desplegada.
          • deploydate (cadena): fecha y hora de despliegue de la imagen (formato AAAA-MM-DD HH:MM:SS).
  • /ous/:id1/rooms/:id2/clients/:id3/status
    • Obtener el de inicio del cliente con identificador id3 del aula
    • Método: GET.
    • Devuelve:
      • clientid (entero): identificador del cliente.
      • ip (cadena): dirección IP del cliente.
      • status (array): estado de inicio del cliente ("off", "initializing", "ogclient", "busy", "linux", "windows" o "nodata").
    • Otros datos que pueden incluirse:
      • clientname (cadena): nombre del cliente.
  • /ous/:id1/repos
    • Listar los repositorios de imágenes definidos en la UO id1.
    • Método: GET.
    • Devuelve:
      • ouid (entero): identificador de la UO.
      • repos (array): datos de los repositorios definidas, compuesta por:
        • repoid (entero): identificador del repositorio.
        • reponame (cadena): nombre del repositorio.
  • /ous/:id1/repos/:id2
    • Obtener los datos del repositorio con identificador id2 de la UO id1.
    • Método: GET.
    • Devuelve:
      • repoid (entero): identificador del repositorio.
      • reponame (cadena): nombre del repositorio.
      • description (cadena): descripción del repositorio.
      • ipaddress (cadena): dirección IP del repositorio.
      • port (entero): puerto de conexión al servicio del repositorio.
  • /ous/:id1/images
    • Listar las imágenes almacenadas en los repositorios definidos en la UO id1.
    • Método: GET.
    • Devuelve:
      • ouid (entero): identificador de la UO.
      • image (array): datos de las imágenes definidas, compuesta por:
        • imageid (entero): identificador de la imagen.
        • imagename (cadena): nombre de la imagen.
  • /ous/:id1/images/:id2
    • Obtener los datos de la imagen con identificador id2 de la UO id1.
    • Método: GET.
    • Devuelve:
      • Datos generales:
        • imageid (entero): identificador de la imagen.
        • imagename (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.
        • 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.
        • path (cadena): camino de la imagen.
      • Datos incluidos si la imagen ha sido generada en el cliente modelo:
        • clientid (entero): identificador del cliente modelo.
        • 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).
    • Otros datos que pueden incluirse:
      • baseid (entero): identificador de la imagen base para una imagen incremental.
  • /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:
      • imageid (entero): identificador de la imagen.
      • imagename (cadena): nombre de la imagen.
      • software (array): datos de las aplicaciones instaladas, compuesta por:
        • application (cadena): nombre y versión de la aplicación o del paquete del sistema operativo.
  • /ous/:id1/images/:id2/boot
    • Iniciar sesión en el sistema operativo de clientes que tengan instalada la imagen con identificador id2 de la UO id1.
    • Parámetros:
      • nclients (entero): nº de clientes a iniciar.
    • Método: POST.
    • Devuelve: (por determinar)
      • sendto (array): datos de los clientes a los que se les ha enviado la orden de iniciar sesión, compuesta por:
        • clientid (entero): identificador del cliente.
    • Otros datos que pueden incluirse en la lista de clientes:
      • clientname (cadena): nombre del cliente.
      • ip (cadena): dirección IP del cliente.