API REST del plugin¶

Convenciones HTTP que debe cumplir la API de tu plugin para integrarse con tablas, formularios y el shell.

Cuándo aplica¶

• Implementas endpoints que alimentan widgets data-table o form.
• Necesitas paginación, orden o búsqueda en listados.
• Expones datos multi-tenant.

Prefijo y montaje¶

• Todas las rutas de plataforma viven bajo /api/v1.
• El APIRouter de tu plugin se monta sin prefijo extra de versión; tú defines el prefijo de dominio (/clients, /booking, etc.).
• El guard de plugins desactiva rutas si el id no está en CORTEX_ENABLED_PLUGINS.

Tenant¶

Envía siempre el header de tenant en peticiones desde el shell o pruebas manuales:

X-Tenant-Id: default

El valor por defecto configurable es CORTEX_DEFAULT_TENANT.

Listados estándar¶

Usa list_endpoint del framework para respuestas compatibles con DataTableWidget:

from cortex_framework.api.list_response import list_endpoint

@router.get("/clients")
async def clients(request: Request) -> dict:
    items = [...]
    return list_endpoint(items, request)

Formato de respuesta¶

{
  "items": [ { "id": "1", "name": "..." } ],
  "meta": {
    "total": 42,
    "page": 1,
    "pageSize": 25
  }
}

También se acepta un array plano; la tabla lo normaliza cuando no hay meta.

Query params que interpreta la tabla¶

Implementación: framework/cortex_framework/api/list_response.py.

Registros individuales¶

• Cada fila debe incluir id (string o UUID) para acciones por fila, edición y bulk.
• GET /recurso/{id} devuelve el objeto para recordPath en formularios de edición.
• Errores: usa HTTPException con códigos HTTP estándar; el shell muestra el mensaje al usuario.

Formularios¶

• GET /api/v1/forms/{formId} — lo sirve el framework desde FormDefinition registrado en bootstrap.
• El submit del widget form hace POST o PUT a la ruta definida en submit.path del widget.
• Tu plugin implementa la persistencia en esas rutas.

CORS y rate limit¶

La API aplica CORS abierto en desarrollo y RateLimitMiddleware según CORTEX_RATE_LIMIT_PER_MINUTE (Redis).

Health y diagnóstico¶

Muchos plugins exponen GET /{namespace}/info como diagnóstico local.

Siguiente paso¶

Columnas de tabla — cómo declarar columnas y filtros que consumen estos listados.