[[TOC(heading=Índice)]] {{{ #!div style="width:50%; background: #ffd; font: bold italic large sans-serif"> 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}}} - Consultar 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}}} - Consultar 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}}} - Método: GET. - Devuelve: - {{{/ous/:id1/rooms/:id2/clients/:id3}}} - Método: GET. - Devuelve: - {{{/ous/:id1/rooms/:id2/clients/:id3/hardware}}} - Método: GET. - Devuelve: - {{{/ous/:id1/rooms/:id2/clients/:id3/diskcfg}}} - Método: GET. - Devuelve: - {{{/ous/:id1/rooms/:id2/clients/:id3/status}}} - Método: GET. - Devuelve: - {{{/ous/:id1/repos}}} - Método: GET. - Devuelve: - {{{/ous/:id1/repos/:id2}}} - Método: GET. - Devuelve: - {{{/ous/:id1/images}}} - Método: GET. - Devuelve: - {{{/ous/:id1/images/:id2}}} - Método: GET. - Devuelve: - {{{/ous/:id1/images/:id2/software}}} - Método: GET. - Devuelve: - {{{/ous/:id1/images/:id2/boot}}} - Parámetros: - Método: POST. - Devuelve: (por determinar)