From 43846b038230c2983401c70eaf32c5e27bf26448 Mon Sep 17 00:00:00 2001 From: lgromero Date: Tue, 29 Oct 2024 13:15:32 +0100 Subject: [PATCH] refs #1084 Adds swagger documentation to all endpoints of ogrepository --- api/repo_api.py | 9 +- api/swagger.yaml | 1510 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1515 insertions(+), 4 deletions(-) create mode 100644 api/swagger.yaml diff --git a/api/repo_api.py b/api/repo_api.py index 70a3d16..fe80c9c 100644 --- a/api/repo_api.py +++ b/api/repo_api.py @@ -20,8 +20,8 @@ import os import subprocess import json from time import sleep - - +from flasgger import Swagger +import yaml # -------------------------------------------------------------------------------------------- # VARIABLES # -------------------------------------------------------------------------------------------- @@ -32,7 +32,6 @@ repo_file = '/opt/opengnsys/etc/repoinfo.json' trash_file = '/opt/opengnsys/etc/trashinfo.json' - # -------------------------------------------------------------------------------------------- # FUNCTIONS # -------------------------------------------------------------------------------------------- @@ -41,7 +40,9 @@ trash_file = '/opt/opengnsys/etc/trashinfo.json' # Creamos una instancia de la aplicación Flask: app = Flask(__name__) - +with open("swagger.yaml", "r") as file: + swagger_template = yaml.safe_load(file) +swagger = Swagger(app, template=swagger_template) # --------------------------------------------------------- diff --git a/api/swagger.yaml b/api/swagger.yaml new file mode 100644 index 0000000..8ac0a39 --- /dev/null +++ b/api/swagger.yaml @@ -0,0 +1,1510 @@ +swagger: "2.0" +info: + title: "Ogrepository API" + version: "1.0" + description: | + API de ogRepository, programada en Flask. + + Responde a peticiones HTTP (enviadas desde ogCore) mediante endpoints, que a su vez ejecutan los scripts Python almacenados en ogRepo. + En ciertos casos, transforma los parámetros recibidos desde el portal, para adaptarlos a los que es necesario enviar a los scripts + (por ejemplo, a partir del ID de una imagen obtiene su nombre, su extensión y el subdirectorio de OU). + + Librerías Python requeridas: Flask (se puede instalar con "sudo apt install python3-flask"). + +paths: + /ogrepository/v1/status: + get: + summary: "Obtener Información de Estado de ogRepository" + description: > + Este endpoint ejecuta el script "getRepoStatus.py" y devuelve su salida en formato JSON, + incluyendo información sobre la CPU, memoria RAM, disco duro, servicios, y procesos específicos de ogRepository. + tags: + - "Estado de ogRepository" + responses: + 200: + description: "La información de estado se obtuvo exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: object + properties: + cpu: + type: object + properties: + used_percentage: + type: string + example: "35%" + ram: + type: object + properties: + total: + type: string + example: "7.8GB" + used: + type: string + example: "0.3GB" + available: + type: string + example: "7.2GB" + used_percentage: + type: string + example: "7%" + disk: + type: object + properties: + total: + type: string + example: "11.7GB" + used: + type: string + example: "7.7GB" + available: + type: string + example: "3.4GB" + used_percentage: + type: string + example: "69%" + services: + type: object + properties: + ssh: + type: string + example: "active" + smbd: + type: string + example: "active" + rsync: + type: string + example: "active" + processes: + type: object + properties: + udp-sender: + type: string + example: "stopped" + uftp: + type: string + example: "stopped" + bttrack: + type: string + example: "stopped" + btlaunchmany: + type: string + example: "stopped" + 500: + description: "Error al consultar y/o devolver la información de estado." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/images: + get: + summary: "Obtener Información de todas las Imágenes" + description: > + Este endpoint ejecuta el script "getRepoInfo.py" con los parámetros "all" y "none" para devolver información + de todas las imágenes almacenadas en el repositorio y en la papelera. + Devuelve detalles como el nombre de la imagen, tipo, nombre del cliente, clonador, compresor, sistema de archivos, + tamaño de los datos, tamaño de la imagen, y hashes MD5. + tags: + - "Imágenes de Repositorio" + responses: + 200: + description: "La información de las imágenes se obtuvo exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: object + properties: + REPOSITORY: + type: object + properties: + directory: + type: string + example: "/opt/opengnsys/images" + images: + type: array + items: + type: object + properties: + name: + type: string + example: "Ubuntu24" + type: + type: string + example: "img" + clientname: + type: string + example: "Ubuntu_24" + clonator: + type: string + example: "partclone" + compressor: + type: string + example: "lzop" + filesystem: + type: string + example: "EXTFS" + datasize: + type: integer + example: 9859634200000 + size: + type: integer + example: 4505673214 + sum: + type: string + example: "065a933c780ab1aaa044435ad5d4bf87" + fullsum: + type: string + example: "33575b9070e4a8043371b8c6ae52b80e" + ous: + type: array + items: + type: object + properties: + subdir: + type: string + example: "OU_subdir" + images: + type: array + items: + type: object + properties: + name: + type: string + example: "Ubuntu20" + type: + type: string + example: "img" + clientname: + type: string + example: "Ubuntu_20" + clonator: + type: string + example: "partclone" + compressor: + type: string + example: "lzop" + filesystem: + type: string + example: "EXTFS" + datasize: + type: integer + example: 8912896000000 + size: + type: integer + example: 3803794535 + sum: + type: string + example: "081a933c780ab1aaa044435ad5d4bf56" + fullsum: + type: string + example: "22735b9070e4a8043371b8c6ae52b90d" + TRASH: + type: object + properties: + directory: + type: string + example: "/opt/opengnsys/images_trash" + images: + type: array + items: + type: object + ous: + type: array + items: + type: object + properties: + subdir: + type: string + example: "CentroVirtual" + images: + type: array + items: + type: object + properties: + name: + type: string + example: "Ubuntu20OLD" + type: + type: string + example: "img" + clientname: + type: string + example: "Ubuntu_20" + clonator: + type: string + example: "partclone" + compressor: + type: string + example: "lzop" + filesystem: + type: string + example: "EXTFS" + datasize: + type: integer + example: 8912896000000 + size: + type: integer + example: 3803794535 + sum: + type: string + example: "081a933c780ab1aaa044435ad5d4bf56" + fullsum: + type: string + example: "22735b9070e4a8043371b8c6ae52b90d" + 500: + description: "Error al consultar y/o devolver la información de las imágenes." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + put: + summary: "Actualizar Información del Repositorio" + description: > + Este endpoint actualiza la información de las imágenes almacenadas en el repositorio, reflejándola en los archivos "repoinfo.json" y "trashinfo.json". + Utiliza el script "updateRepoInfo.py", que también ejecuta "updateTrashInfo.py". + Este proceso se realiza para mantener actualizados los datos del repositorio y la papelera, y debería ser invocado cada vez que se elimine o cree una imagen. + tags: + - "Imágenes de Repositorio" + responses: + 200: + description: "La actualización de la información del repositorio se realizó exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Repository info updated successfully" + 500: + description: "Error al actualizar la información de las imágenes." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/images/{imageId}: + get: + summary: "Obtener Información de una Imagen concreta" + description: > + Este endpoint devuelve información de la imagen especificada mediante su ID en formato JSON. + Puede utilizar el script "getRepoInfo.py" que recibe como parámetros el nombre de la imagen con extensión y el subdirectorio correspondiente a la OU (o "none" si no es el caso). + La imagen puede estar en el archivo "/opt/opengnsys/etc/repoinfo.json" (si está almacenada) o en "/opt/opengnsys/etc/trashinfo.json" (si está en la papelera). + tags: + - "Imágenes de Repositorio" + parameters: + - name: imageId + in: path + required: true + type: string + description: "El ID de la imagen (corresponde al hash MD5 'fullsum' de la imagen)" + responses: + 200: + description: "La información de la imagen se obtuvo exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: object + properties: + directory: + type: string + example: "/opt/opengnsys/images" + images: + type: array + items: + type: object + properties: + name: + type: string + example: "Windows10" + type: + type: string + example: "img" + clientname: + type: string + example: "Windows_10" + clonator: + type: string + example: "partclone" + compressor: + type: string + example: "lzop" + filesystem: + type: string + example: "NTFS" + datasize: + type: integer + example: 9859634200000 + size: + type: integer + example: 4505673214 + sum: + type: string + example: "065a933c780ab1aaa044435ad5d4bf87" + fullsum: + type: string + example: "33575b9070e4a8043371b8c6ae52b80e" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found" + 500: + description: "Error al consultar y/o devolver la información de la imagen." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + delete: + summary: "Eliminar una Imagen" + description: > + Este endpoint elimina la imagen especificada como parámetro (y todos sus archivos asociados), + moviéndolos a la papelera o eliminándolos permanentemente dependiendo del parámetro "method". + Utiliza el script "deleteImage.py" que recibe el nombre de la imagen (con extensión y subdirectorio correspondiente a la OU, si aplica) + como primer parámetro, y opcionalmente el parámetro "-p" para eliminación permanente. + tags: + - "Imágenes de Repositorio" + parameters: + - name: imageId + in: path + required: true + type: string + description: "El ID de la imagen (corresponde al hash MD5 'fullsum' de la imagen)" + - name: method + in: query + required: false + type: string + description: "Método de eliminación (puede ser 'trash' para enviar a la papelera o 'permanent' para eliminar definitivamente)" + responses: + 200: + description: "La imagen se eliminó exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image deleted successfully" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found (inexistent or deleted)" + 500: + description: > + Error al eliminar la imagen. Puede ocurrir debido a: + - Un error de ejecución del script (con salida no 0). + - Una excepción inesperada durante el proceso. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la eliminación de la imagen." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/status/images/{imageId}: + get: + summary: "Chequear Integridad de Imagen" + description: > + Este endpoint comprueba la integridad de la imagen especificada como parámetro, comparando el tamaño y el hash MD5 del último MB con los valores almacenados en los archivos ".size" y ".sum". + Utiliza el script "checkImage.py", que recibe el nombre de la imagen (con extensión) y el subdirectorio correspondiente a la OU, si aplica. + tags: + - "Integridad de Imágenes" + parameters: + - name: imageId + in: path + required: true + type: string + description: "El ID de la imagen (corresponde al hash MD5 'fullsum' de la imagen)" + responses: + 200: + description: > + La imagen se ha chequeado exitosamente. El chequeo puede devolver dos resultados: + - Si pasa la verificación de integridad. + - Si no pasa la verificación de integridad. + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image file passed the Integrity Check correctly" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found (inexistent or deleted)" + 500: + description: > + Error al chequear la imagen. Puede ocurrir debido a una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + 200 (KO): + description: "La imagen se ha chequeado correctamente, pero no ha pasado el test de integridad." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image file didn't pass the Integrity Check" + + /ogrepository/v1/trash/images: + post: + summary: "Recuperar una Imagen" + description: > + Este endpoint recupera la imagen especificada, moviéndola desde la papelera al repositorio de imágenes. + Utiliza el script "recoverImage.py", que recibe el nombre de la imagen (con extensión y subdirectorio correspondiente a la OU, si aplica). + tags: + - "Imágenes de Papelera" + parameters: + - name: ID_img + in: body + required: true + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + schema: + type: object + properties: + ID_img: + type: string + example: "image_id" + responses: + 200: + description: "La imagen se recuperó exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image recovered successfully" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found (inexistent or recovered previously)" + 500: + description: > + Error al recuperar la imagen. Puede ocurrir debido a: + - Un error de ejecución del script (con salida no 0). + - Una excepción inesperada durante el proceso. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la recuperación de la imagen." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/trash/images/{imageId}: + delete: + summary: "Eliminar una Imagen de la Papelera" + description: > + Este endpoint elimina permanentemente la imagen especificada desde la papelera. + Utiliza el script "deleteTrashImage.py", que recibe el nombre de la imagen (con extensión y subdirectorio correspondiente a la OU, si aplica). + tags: + - "Imágenes de Papelera" + parameters: + - name: imageId + in: path + required: true + type: string + description: "El ID de la imagen (corresponde al hash MD5 'fullsum' de la imagen en la papelera)" + responses: + 200: + description: "La imagen se eliminó exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image deleted successfully" + 400: + description: "No se ha encontrado la imagen especificada en la papelera." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found at trash" + 500: + description: > + Error al eliminar la imagen desde la papelera. Puede ocurrir debido a: + - Un error de ejecución del script (con salida no 0). + - Una excepción inesperada durante el proceso. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la eliminación de la imagen desde la papelera." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/repo/images: + post: + summary: "Importar una Imagen" + description: > + Este endpoint importa la imagen especificada desde un servidor remoto al servidor local. + Utiliza el script "importImage.py", que recibe como parámetros el nombre de la imagen, la IP o hostname del servidor remoto, + el usuario para la conexión, y el subdirectorio correspondiente a la OU (si aplica). + tags: + - "Imágenes de Repositorio" + parameters: + - name: image + in: body + required: true + description: "Nombre de la imagen (con extensión)" + schema: + type: object + properties: + image: + type: string + example: "Windows10.img" + ou_subdir: + type: string + description: "Subdirectorio correspondiente a la OU (o 'none' si no es el caso)" + example: "none" + repo_ip: + type: string + description: "Dirección IP del repositorio remoto" + example: "192.168.56.100" + user: + type: string + description: "Usuario para acceder al repositorio remoto" + example: "user_name" + responses: + 200: + description: "La imagen se ha importado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image imported successfully" + 400: + description: "Error de conexión o imagen no disponible en el servidor remoto." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Can't connect to remote server | Remote image not found | Remote image is locked" + 500: + description: > + Error interno al importar la imagen. Puede ocurrir debido a un problema en la ejecución del script o una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la importación de la imagen." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + put: + summary: "Exportar una Imagen" + description: > + Este endpoint exporta la imagen especificada desde el servidor local a un servidor remoto. + Utiliza el script "exportImage.py", que recibe como parámetros el nombre de la imagen, la IP o hostname del servidor remoto, + el usuario para la conexión, y el subdirectorio correspondiente a la OU (si aplica). + tags: + - "Imágenes de Repositorio" + parameters: + - name: ID_img + in: body + required: true + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + schema: + type: object + properties: + ID_img: + type: string + example: "image_id" + repo_ip: + type: string + description: "Dirección IP del repositorio remoto" + example: "192.168.56.100" + user: + type: string + description: "Usuario para acceder al repositorio remoto" + example: "user_name" + responses: + 200: + description: "La imagen se ha exportado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image exported successfully" + 400: + description: "Error de conexión o imagen no disponible en el servidor remoto." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Image is locked | Can't connect to remote server | Image already exists on remote server" + 500: + description: > + Error interno al exportar la imagen. Puede ocurrir debido a un problema en la ejecución del script o una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la exportación de la imagen." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + /ogrepository/v1/images/torrentsum: + post: + summary: "Crear archivos auxiliares" + description: > + Este endpoint crea los archivos ".size", ".sum", ".full.sum" y ".torrent" para la imagen especificada. + Utiliza el script "createTorrentSum.py", que recibe como parámetro el nombre de la imagen (con subdirectorio de OU, si aplica). + tags: + - "Archivos Auxiliares de Imágenes" + parameters: + - name: image + in: body + required: true + description: "Nombre de la imagen (con extensión)" + schema: + type: object + properties: + image: + type: string + example: "Windows10.img" + ou_subdir: + type: string + description: "Subdirectorio correspondiente a la OU (o 'none' si no es el caso)" + example: "none" + responses: + 200: + description: "Los archivos se han creado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Files created successfully" + 400: + description: "Error de conexión o imagen no disponible en el servidor remoto." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Image not found | Image is locked" + 500: + description: > + Error interno al crear los archivos auxiliares. Puede ocurrir debido a un problema en la ejecución del script o una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la creación de los archivos auxiliares." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/wol: + post: + summary: "Enviar paquete Wake On Lan" + description: > + Este endpoint envía un paquete mágico Wake On Lan (WOL) a la dirección MAC especificada, a través de la IP de broadcast especificada. + Utiliza el script "sendWakeOnLan.py", que recibe como parámetros la IP de broadcast y la dirección MAC del equipo a encender. + tags: + - "Wake On Lan" + parameters: + - name: broadcast_ip + in: body + required: true + description: "IP de broadcast a la que se enviará el paquete WOL" + schema: + type: object + properties: + broadcast_ip: + type: string + example: "255.255.255.255" + mac: + type: string + description: "Dirección MAC del equipo a encender" + example: "00:19:99:5c:bb:bb" + responses: + 200: + description: "El paquete Wake On Lan se ha enviado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Wake On Lan packet sent successfully" + 500: + description: > + Error interno al enviar el paquete Wake On Lan. Puede ocurrir debido a un problema en la ejecución del script o una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante el envío del paquete Wake On Lan." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/udpcast: + get: + summary: "Ver Estado de Transmisiones UDPcast" + description: > + Este endpoint devuelve información sobre los procesos activos de "udp-sender" en formato JSON, + permitiendo comprobar las transferencias UDPcast activas. Utiliza el script "getUDPcastInfo.py" para obtener esta información. + tags: + - "Transferencia de Imágenes" + responses: + 200: + description: "La información de las transmisiones UDPcast activas se obtuvo exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: object + additionalProperties: + type: object + properties: + image_id: + type: string + example: "22735b9070e4a8043371b8c6ae52b90d" + image_name: + type: string + example: "Ubuntu20.img" + 400: + description: "No se han encontrado transmisiones UDPcast activas." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "No UDPCast active transmissions" + 500: + description: > + Error al comprobar las transmisiones UDPcast activas, posiblemente debido a un error inesperado durante la ejecución del script. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la comprobación de transmisiones UDPcast activas." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Unexpected error checking UDPcast transmissions" + post: + summary: "Enviar una Imagen mediante UDPcast" + description: > + Este endpoint envía una imagen especificada a través de UDPcast utilizando el script "sendFileMcast.py". + Recibe la imagen y los parámetros de configuración de transferencia, que son usados para construir la cadena de parámetros que se envía al script. + tags: + - "Transferencia de Imágenes" + parameters: + - name: ID_img + in: body + required: true + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + schema: + type: object + properties: + ID_img: + type: string + example: "image_id" + port: + type: string + description: "Puerto Multicast a utilizar para la transmisión" + example: "9000" + method: + type: string + description: "Modalidad de transmisión (puede ser 'half' o 'full' para half-duplex o full-duplex)" + example: "full" + ip: + type: string + description: "IP Multicast a la que se enviará la imagen" + example: "239.194.17.2" + bitrate: + type: string + description: "Velocidad de transmisión en Mbps" + example: "70M" + nclients: + type: integer + description: "Número mínimo de clientes" + example: 20 + maxtime: + type: integer + description: "Tiempo máximo de espera en segundos" + example: 120 + responses: + 200: + description: "La imagen se ha enviado exitosamente mediante UDPcast." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image sent successfully" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found" + 500: + description: > + Error interno al enviar la imagen mediante UDPcast. Puede ocurrir debido a un problema en la ejecución del script o una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante el envío de la imagen mediante UDPcast." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + /ogrepository/v1/uftp: + get: + summary: "Ver Estado de Transmisiones UFTP" + description: > + Este endpoint devuelve información sobre los procesos activos de "uftp" en formato JSON, + permitiendo comprobar las transferencias UFTP activas. Utiliza el script "getUFTPInfo.py" para obtener esta información. + tags: + - "Transferencia de Imágenes" + responses: + 200: + description: "La información de las transmisiones UFTP activas se obtuvo exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: object + additionalProperties: + type: object + properties: + image_id: + type: string + example: "22735b9070e4a8043371b8c6ae52b90d" + image_name: + type: string + example: "Ubuntu20.img" + 400: + description: "No se han encontrado transmisiones UFTP activas." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "No UFTP active transmissions" + 500: + description: > + Error al comprobar las transmisiones UFTP activas, posiblemente debido a un error inesperado durante la ejecución del script. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante la comprobación de transmisiones UFTP activas." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Unexpected error checking UFTP transmissions" + post: + summary: "Enviar una Imagen mediante UFTP" + description: > + Este endpoint envía una imagen especificada a través de UFTP, utilizando el script "sendFileUFTP.py". + Requiere que los clientes ogLive estén previamente en escucha con un daemon "UFTPD" ejecutando el script "listenUFTPD.py". + Recibe la imagen y los parámetros de configuración de transferencia, que son usados para construir la cadena de parámetros que se envía al script. + tags: + - "Transferencia de Imágenes" + parameters: + - name: ID_img + in: body + required: true + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + schema: + type: object + properties: + ID_img: + type: string + example: "image_id" + port: + type: string + description: "Puerto para la transmisión UFTP" + example: "9000" + ip: + type: string + description: "IP Unicast o Multicast para la transmisión" + example: "239.194.17.2" + bitrate: + type: string + description: "Velocidad de transmisión (con 'K' para Kbps, 'M' para Mbps, o 'G' para Gbps)" + example: "1G" + responses: + 200: + description: "La imagen se ha enviado exitosamente mediante UFTP." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image sent successfully" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found" + 500: + description: > + Error interno al enviar la imagen mediante UFTP. Puede ocurrir debido a un problema en la ejecución del script o una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Script execution error description." + 500 (Exception): + description: "Error inesperado durante el envío de la imagen mediante UFTP." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + + + /ogrepository/v1/p2p: + post: + summary: "Enviar una Imagen mediante P2P" + description: > + Este endpoint inicia el tracker y el seeder de torrents para enviar una imagen especificada mediante P2P. + Utiliza los scripts "runTorrentTracker.py" y "runTorrentSeeder.py" para iniciar el tracker y el seeder en el directorio de la imagen. + tags: + - "Transferencia de Imágenes" + parameters: + - name: ID_img + in: body + required: true + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + schema: + type: object + properties: + ID_img: + type: string + example: "image_id" + responses: + 200: + description: "La imagen se está enviando exitosamente a través de P2P." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Tracker and Seeder serving image correctly" + 400: + description: "No se ha encontrado la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Image not found" + 500: + description: > + Error al intentar iniciar el tracker o el seeder para el envío P2P. + Puede ocurrir si alguno de los procesos no se inicia correctamente o si ocurre una excepción inesperada. + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Tracker or Seeder (or both) not running" + 500 (Exception): + description: "Error inesperado durante el proceso de envío P2P." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Generic error description for unexpected exceptions." + delete: + summary: "Cancelar Transmisiones P2P" + description: > + Este endpoint cancela todas las transmisiones P2P activas, finalizando los procesos "bttrack" (tracker) y "btlaunchmany.bittornado" (seeder). + Utiliza el script "stopP2P.py" para detener las transmisiones P2P activas en el servidor. + tags: + - "Transferencia de Imágenes" + responses: + 200: + description: "Las transmisiones P2P se han cancelado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "P2P transmissions canceled successfully" + 500 (Error del script): + description: "Error en la ejecución del script durante la cancelación de las transmisiones P2P." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Detailed error message from script stderr output." + 500 (Excepción general): + description: "Excepción inesperada durante la cancelación de las transmisiones P2P." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "General error description for unexpected exceptions" + + /ogrepository/v1/udpcast/images/{ID_img}: + delete: + summary: "Cancelar Transmisión UDPcast" + description: > + Este endpoint cancela la transmisión UDPcast activa de una imagen especificada, deteniendo el proceso "udp-sender" asociado. + Utiliza el script "stopUDPcast.py" para finalizar la transmisión. + tags: + - "Transferencia de Imágenes" + parameters: + - name: ID_img + in: path + required: true + type: string + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + example: "image_id" + responses: + 200: + description: "La transmisión UDPcast se ha cancelado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image transmission canceled successfully" + 400: + description: "No se ha encontrado la imagen especificada o no hay transmisiones UDPcast activas para la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "No UDPCast active transmissions for specified image" + 500 (Error del script): + description: "Error en la ejecución del script durante la cancelación de la transmisión." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Detailed error message from script stderr output." + 500 (Error en verificación): + description: "Error inesperado al verificar las transmisiones UDPcast activas." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Unexpected error checking UDPcast transmissions" + 500 (Error en finalización): + description: "Error inesperado al finalizar la transmisión UDPcast." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Unexpected error finalizing UDPcast transmission" + 500 (Excepción general): + description: "Excepción inesperada durante la cancelación de la transmisión UDPcast." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "General error description for unexpected exceptions" + + /ogrepository/v1/uftp/images/{ID_img}: + delete: + summary: "Cancelar Transmisión UFTP" + description: > + Este endpoint cancela la transmisión UFTP activa de una imagen especificada, deteniendo el proceso "uftp" asociado. + Utiliza el script "stopUFTP.py" para finalizar la transmisión. + tags: + - "Transferencia de Imágenes" + parameters: + - name: ID_img + in: path + required: true + type: string + description: "Identificador de la imagen (correspondiente al contenido del archivo 'full.sum' asociado)" + example: "image_id" + responses: + 200: + description: "La transmisión UFTP se ha cancelado exitosamente." + schema: + type: object + properties: + success: + type: boolean + example: true + output: + type: string + example: "Image transmission canceled successfully" + 400: + description: "No se ha encontrado la imagen especificada o no hay transmisiones UFTP activas para la imagen especificada." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "No UFTP active transmissions for specified image" + 500 (Error del script): + description: "Error en la ejecución del script durante la cancelación de la transmisión." + schema: + type: object + properties: + success: + type: boolean + example: false + error: + type: string + example: "Detailed error message from script stderr output." + 500 (Error en verificación): + description: "Error inesperado al verificar las transmisiones UFTP activas." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Unexpected error checking UFTP transmissions" + 500 (Error en finalización): + description: "Error inesperado al finalizar la transmisión UFTP." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "Unexpected error finalizing UFTP transmission" + 500 (Excepción general): + description: "Excepción inesperada durante la cancelación de la transmisión UFTP." + schema: + type: object + properties: + success: + type: boolean + example: false + exception: + type: string + example: "General error description for unexpected exceptions" + +