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

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.');
}
```