a2host/docs/03-api/api-specification.md

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-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:

{
  "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
{
  "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
{
  "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 en apache2ctl 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 es true, 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.');
}