14 KiB
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 <token> 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-8oapplication/problem+jsonen 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:
{
"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):
{
"username": "admin",
"password": "PasswordSuperSegura2026!"
}
- Respuesta Exitosa (
200 OK):- Cabeceras:
Set-Cookie: a2host_session=s%3A...; Path=/; HttpOnly; SameSite=Strict
- Cabeceras:
{
"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
- Cabeceras:
{
"success": true,
"message": "Sesión finalizada exitosamente"
}
GET /api/auth/me
Retorna la información del usuario autenticado.
- Respuesta Exitosa (
200 OK):
{
"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):
[
{
"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):
{
"username": "developer1",
"password": "ClaveSegura123!",
"fullName": "Dev Front Junior",
"role": "operator"
}
- Respuesta Exitosa (
201 Created):
{
"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):
[
{
"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:
{
"name": "portfolio",
"type": "static"
}
Payload Modo B — Proxy Inverso por Puerto:
{
"name": "fastapi-microservice",
"type": "proxy",
"port": 8000
}
- Respuesta Exitosa (
201 Created):
{
"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.{ "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.{ "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 enapache2ctl configtest(Rollback activado).{ "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):
{
"enabled": false
}
- Respuesta Exitosa (
200 OK):
{
"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 estrue, elimina/var/www/<name>.
-
Ejemplo de Petición:
DELETE /api/subdomains/old-campaign?deleteFiles=true -
Respuesta Exitosa (
200 OK):
{
"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):
[
{
"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):
{
"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):
{
"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
# 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)
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.');
}