# Especificación Formal de la API REST ## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`) **Estándar:** OpenAPI 3.1.0 / RFC 7807 (Problem Details for HTTP APIs) **Proyecto:** a2host — Lightweight Subdomain Orchestrator **Versión:** 1.0.0 **Fecha:** 19 de Noviembre de 2026 **Base URL:** `http://127.0.0.1:3005/api` o `https://panel.elingejose.com/api` **Autor:** Arquitectura y Redacción Técnica (@docs) --- ### Registro de Revisiones | Versión | Fecha | Autor | Descripción | | :---: | :---: | :---: | :--- | | `1.0.0` | 2026-11-19 | Arquitecto de Documentación (@docs) | Especificación exhaustiva de endpoints, esquemas de entrada/salida, códigos HTTP y manejo de errores RFC 7807. | --- ## 1. Convenciones y Protocolo de Transporte ### 1.1 Autenticación y Cabeceras La API implementa autenticación basada en sesiones criptográficas con cookies seguras o cabecera `Authorization: Bearer ` para clientes de automatización. - **Cookie de Sesión:** `a2host_session` (Flags: `HttpOnly; SameSite=Strict; Path=/; Priority=High`). - **Content-Type Solicitado:** `application/json; charset=utf-8`. - **Content-Type de Respuesta:** `application/json; charset=utf-8` o `application/problem+json` en caso de error. ### 1.2 Formato Estándar de Error (RFC 7807) En caso de fallo en validación o ejecución en Apache, el sistema responderá con la siguiente estructura: ```json { "type": "https://a2host.elingejose.com/errors/apache-syntax-error", "title": "Error de Sintaxis en Apache2", "status": 422, "detail": "AH00526: Syntax error on line 4 of /etc/apache2/sites-available/demo.conf: Invalid command 'ProxPass', perhaps misspelled", "instance": "/api/subdomains", "code": "APACHE_CONFIGTEST_FAILED", "rollbackExecuted": true, "timestamp": "2026-11-19T14:22:10.450Z" } ``` --- ## 2. Matriz de Endpoints | Categoría | Método | Endpoint | Roles Permitidos | Descripción | | :--- | :---: | :--- | :---: | :--- | | **Auth** | `POST` | `/api/auth/login` | Público | Autenticación con credenciales y emisión de cookie de sesión. | | **Auth** | `POST` | `/api/auth/logout` | Autenticado | Invalidación de sesión y eliminación de cookie. | | **Auth** | `GET` | `/api/auth/me` | Autenticado | Retorna el perfil y privilegios del usuario en sesión. | | **Users** | `GET` | `/api/users` | `admin` | Lista todos los usuarios/operadores registrados. | | **Users** | `POST` | `/api/users` | `admin` | Crea un nuevo operador o administrador. | | **Users** | `PUT` | `/api/users/:id` | `admin` | Modifica rol, nombre o contraseña de un usuario. | | **Users** | `DELETE` | `/api/users/:id` | `admin` | Elimina una cuenta de usuario (no auto-eliminación). | | **Subdomains** | `GET` | `/api/subdomains` | Autenticado | Lista todos los VirtualHosts de Apache y su estado. | | **Subdomains** | `POST` | `/api/subdomains` | Autenticado | Aprovisiona un subdominio Modo A o B con Rollback Atómico. | | **Subdomains** | `GET` | `/api/subdomains/:name` | Autenticado | Obtiene la configuración y directivas de un subdominio. | | **Subdomains** | `PUT` | `/api/subdomains/:name` | Autenticado | Actualiza la configuración de un subdominio existente. | | **Subdomains** | `POST` | `/api/subdomains/:name/toggle` | Autenticado | Alterna estado Habilitado/Deshabilitado (`a2ensite`/`a2dissite`). | | **Subdomains** | `DELETE` | `/api/subdomains/:name` | `admin` | Deshabilita y purga el `.conf` (opcionalmente purga `/var/www`). | | **Folders** | `GET` | `/api/folders` | Autenticado | Lista directorios web en `/var/www/` con permisos y tamaños. | | **Folders** | `GET` | `/api/folders/:name/files` | Autenticado | Lista archivos contenidos dentro de `/var/www/:name`. | | **System** | `GET` | `/api/system/stats` | Autenticado | Métricas de memoria (Host/Node), CPU, uptime y estado Apache. | --- ## 3. Especificación Detallada de Endpoints ### 3.1 Módulo: Autenticación (`/api/auth`) #### `POST /api/auth/login` Autentica al operador mediante usuario y contraseña comparados mediante `scrypt`. - **Cuerpo de la Solicitud (`application/json`):** ```json { "username": "admin", "password": "PasswordSuperSegura2026!" } ``` - **Respuesta Exitosa (`200 OK`):** - **Cabeceras:** `Set-Cookie: a2host_session=s%3A...; Path=/; HttpOnly; SameSite=Strict` ```json { "success": true, "message": "Autenticación satisfactoria", "user": { "id": "u-4f38-9e12", "username": "admin", "role": "admin", "fullName": "Administrador Principal" } } ``` - **Errores Posibles:** - `400 Bad Request`: Campos requeridos faltantes. - `401 Unauthorized`: Credenciales no válidas o usuario inactivo. - `429 Too Many Requests`: Superado el límite de 5 intentos fallidos por IP en 15 minutos. --- #### `POST /api/auth/logout` Cierra la sesión activa revocando la cookie. - **Respuesta Exitosa (`200 OK`):** - **Cabeceras:** `Set-Cookie: a2host_session=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT` ```json { "success": true, "message": "Sesión finalizada exitosamente" } ``` --- #### `GET /api/auth/me` Retorna la información del usuario autenticado. - **Respuesta Exitosa (`200 OK`):** ```json { "id": "u-4f38-9e12", "username": "admin", "role": "admin", "fullName": "Administrador Principal", "permissions": ["subdomains:read", "subdomains:write", "subdomains:delete", "users:manage", "system:stats"] } ``` --- ### 3.2 Módulo: Gestión de Usuarios (`/api/users`) #### `GET /api/users` Retorna el catálogo de operadores del sistema (Solo rol `admin`). - **Respuesta Exitosa (`200 OK`):** ```json [ { "id": "u-4f38-9e12", "username": "admin", "fullName": "Administrador Principal", "role": "admin", "active": true, "createdAt": "2026-11-01T10:00:00.000Z", "lastLogin": "2026-11-19T14:00:00.000Z" }, { "id": "u-7c81-1a34", "username": "devops_jose", "fullName": "José Ingeniero", "role": "operator", "active": true, "createdAt": "2026-11-05T12:30:00.000Z", "lastLogin": "2026-11-18T18:45:00.000Z" } ] ``` --- #### `POST /api/users` Crea una nueva cuenta de operador o administrador. - **Cuerpo de la Solicitud (`application/json`):** ```json { "username": "developer1", "password": "ClaveSegura123!", "fullName": "Dev Front Junior", "role": "operator" } ``` - **Respuesta Exitosa (`201 Created`):** ```json { "success": true, "message": "Usuario creado satisfactoriamente", "user": { "id": "u-9b22-8d77", "username": "developer1", "fullName": "Dev Front Junior", "role": "operator", "active": true } } ``` - **Errores Posibles:** - `409 Conflict`: El nombre de usuario ya está registrado en el sistema. --- ### 3.3 Módulo: Subdominios (`/api/subdomains`) #### `GET /api/subdomains` Escanea `/etc/apache2/sites-available/` y `/etc/apache2/sites-enabled/` retornando la lista normalizada de subdominios. - **Respuesta Exitosa (`200 OK`):** ```json [ { "name": "git", "fullDomain": "git.elingejose.com", "type": "proxy", "target": "http://127.0.0.1:3000", "port": 3000, "enabled": true, "protected": true, "configFile": "/etc/apache2/sites-available/git.conf", "hasDirectory": false }, { "name": "blog", "fullDomain": "blog.elingejose.com", "type": "static", "target": "/var/www/blog", "port": null, "enabled": true, "protected": false, "configFile": "/etc/apache2/sites-available/blog.conf", "hasDirectory": true }, { "name": "staging-api", "fullDomain": "staging-api.elingejose.com", "type": "proxy", "target": "http://127.0.0.1:5050", "port": 5050, "enabled": false, "protected": false, "configFile": "/etc/apache2/sites-available/staging-api.conf", "hasDirectory": false } ] ``` --- #### `POST /api/subdomains` Aprovisiona un nuevo subdominio con validación estricta y rollback automático. ##### Payload Modo A — Proyecto Web Estático / PHP: ```json { "name": "portfolio", "type": "static" } ``` ##### Payload Modo B — Proxy Inverso por Puerto: ```json { "name": "fastapi-microservice", "type": "proxy", "port": 8000 } ``` - **Respuesta Exitosa (`201 Created`):** ```json { "success": true, "message": "Subdominio 'portfolio' creado y habilitado exitosamente", "subdomain": { "name": "portfolio", "fullDomain": "portfolio.elingejose.com", "type": "static", "target": "/var/www/portfolio", "enabled": true, "protected": false } } ``` - **Errores Posibles y Respuestas RFC 7807:** - `400 Bad Request`: Formato de subdominio no conforme a `^[a-z0-9-]+$` o longitud > 63. ```json { "type": "https://a2host.elingejose.com/errors/invalid-subdomain-format", "title": "Nombre de Subdominio Inválido", "status": 400, "detail": "El nombre solo puede contener letras minúsculas, dígitos y guiones (^[a-z0-9-]+$)", "code": "VALIDATION_FAILED" } ``` - `400 Bad Request`: Puerto en lista de reservados o fuera del rango 1024-65535. ```json { "type": "https://a2host.elingejose.com/errors/reserved-port", "title": "Puerto Reservado o Inválido", "status": 400, "detail": "El puerto 3000 está reservado por el sistema (Gitea). Seleccione un puerto libre entre 1024 y 65535.", "code": "PORT_RESERVED" } ``` - `409 Conflict`: Ya existe un VirtualHost con ese nombre o puerto. - `422 Unprocessable Entity`: Fallo en `apache2ctl configtest` (Rollback activado). ```json { "type": "https://a2host.elingejose.com/errors/apache-syntax-error", "title": "Error de Sintaxis en Apache2", "status": 422, "detail": "AH00526: Syntax error on line 3: Unknown directive ProxyPasss", "code": "APACHE_CONFIGTEST_FAILED", "rollbackExecuted": true } ``` --- #### `POST /api/subdomains/:name/toggle` Alterna el estado operativo del subdominio (`enabled` $\leftrightarrow$ `disabled`). - **Parámetros de Ruta:** `name` (Nombre del subdominio sin el dominio base). - **Cuerpo de la Solicitud (`application/json`):** ```json { "enabled": false } ``` - **Respuesta Exitosa (`200 OK`):** ```json { "success": true, "message": "Subdominio 'staging-api' deshabilitado exitosamente", "subdomain": { "name": "staging-api", "enabled": false } } ``` - **Errores:** - `403 Forbidden`: El sitio está protegido (`git.conf`, `000-default.conf`). - `404 Not Found`: No existe el subdominio especificado. --- #### `DELETE /api/subdomains/:name` Elimina un subdominio de Apache. Permite opcionalmente borrar los archivos web físicos. - **Parámetros de Ruta:** `name`. - **Parámetros de Consulta (Query String):** - `deleteFiles` (Booleano, default: `false`): Si es `true`, elimina `/var/www/`. - **Ejemplo de Petición:** `DELETE /api/subdomains/old-campaign?deleteFiles=true` - **Respuesta Exitosa (`200 OK`):** ```json { "success": true, "message": "Subdominio 'old-campaign' eliminado exitosamente. Archivos web purgados del disco.", "deletedFiles": true } ``` - **Errores:** - `403 Forbidden`: Intento de eliminar un sitio protegido (`git.conf`, `000-default.conf`). --- ### 3.4 Módulo: Explorador de Carpetas (`/api/folders`) #### `GET /api/folders` Lista todas las carpetas contenidas en `/var/www/`, su tamaño total en disco y sus permisos UNIX. - **Respuesta Exitosa (`200 OK`):** ```json [ { "folderName": "blog", "path": "/var/www/blog", "sizeBytes": 458920, "sizeFormatted": "448.1 KB", "owner": "ggc", "group": "www-data", "permissions": "2775", "isSGID": true, "fileCount": 12, "lastModified": "2026-11-18T20:15:00.000Z" }, { "folderName": "portfolio", "path": "/var/www/portfolio", "sizeBytes": 2048, "sizeFormatted": "2.0 KB", "owner": "ggc", "group": "www-data", "permissions": "2775", "isSGID": true, "fileCount": 1, "lastModified": "2026-11-19T14:30:00.000Z" } ] ``` --- #### `GET /api/folders/:name/files` Lista los archivos dentro de `/var/www/:name`. - **Respuesta Exitosa (`200 OK`):** ```json { "folder": "portfolio", "files": [ { "name": "index.html", "type": "file", "sizeBytes": 1420, "sizeFormatted": "1.38 KB", "permissions": "0664", "lastModified": "2026-11-19T14:30:00.000Z" } ] } ``` --- ### 3.5 Módulo: Telemetría y Salud del Sistema (`/api/system/stats`) #### `GET /api/system/stats` Provee una instantánea no bloqueante del estado del VPS y del proceso Node.js. - **Respuesta Exitosa (`200 OK`):** ```json { "server": { "hostname": "vps-jose", "platform": "linux", "arch": "x64", "nodeVersion": "v22.11.0", "uptimeSeconds": 1548200, "uptimeFormatted": "17d 22h 3m" }, "memory": { "hostTotalBytes": 1073741824, "hostFreeBytes": 412352512, "hostUsedBytes": 661389312, "hostUsedPercent": 61.6, "processRssBytes": 31457280, "processRssFormatted": "30.0 MB", "processHeapUsedBytes": 14680064, "processHeapUsedFormatted": "14.0 MB", "pm2LimitFormatted": "120 MB" }, "apache": { "installed": true, "mockMode": false, "active": true, "sitesAvailableCount": 8, "sitesEnabledCount": 6 } } ``` --- ## 4. Ejemplos Prácticos de Consumo ### 4.1 Login y Creación de Proxy Inverso mediante `curl` ```bash # 1. Autenticarse y guardar cookie en cookiejar curl -X POST https://panel.elingejose.com/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"MiPasswordSegura2026"}' \ -c cookies.txt # 2. Crear subdominio Modo B (Proxy al puerto 5000) curl -X POST https://panel.elingejose.com/api/subdomains \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{"name":"ai-agent","type":"proxy","port":5000}' ``` ### 4.2 Deshabilitar un Subdominio con `fetch` (JavaScript Cliente) ```javascript const response = await fetch('/api/subdomains/ai-agent/toggle', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ enabled: false }), credentials: 'same-origin' }); if (!response.ok) { const errorData = await response.json(); console.error('Error al pausar subdominio:', errorData.detail); } else { console.log('Subdominio pausado exitosamente.'); } ```