503 lines
14 KiB
Markdown
503 lines
14 KiB
Markdown
# 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:
|
|
|
|
```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/<name>`.
|
|
|
|
- **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.');
|
|
}
|
|
```
|