Skip to content
PageWell
API del backend: qué JSON lee el frontend ISAEL JAVIER FATAMA GODOYUpdated 2026-11-16

Copy


API del backend: qué JSON lee el frontend

6 min read Updated 2026-11-16

Base: http://localhost:8080. Todo es JSON en UTF-8. La misma información, navegable, está en Swagger: http://localhost:8080/swagger-ui.html (el JSON de OpenAPI está en /v3/api-docs).

El backend no filtra ni pagina: entrega los datos y el frontend filtra, busca, pagina y calcula los indicadores.

Resumen de endpoints

Método y ruta Pantalla que lo usa Devuelve
GET /api/jobs Jobs Jobs disponibles
GET /api/datasets Jobs Carpetas de data/
POST /api/executions Jobs La ejecución creada
GET /api/executions Ejecuciones, Jobs, Calidad Historial
GET /api/executions/{id} Ejecuciones Estado, resultado y etapas
GET /api/executions/{id}/log Ejecuciones Texto: salida del proceso
GET /api/executions/{id}/quality Calidad Reporte de calidad
GET /api/executions/{id}/rejected Calidad Filas rechazadas y su motivo
GET /api/dashboard/performance Dashboard Filas de la tabla RENDIMIENTO
GET /api/dashboard/courses Dashboard Filas de la tabla CURSOS_RESUMEN
GET /api/dashboard/tables Dashboard Conteo de filas de cada tabla
GET /api/dashboard/loads Dashboard Filas insertadas y actualizadas por cada carga

Jobs

GET /api/jobs

[
  { "type": "RENDIMIENTO_ACADEMICO", "label": "Rendimiento académico", "input": "DATASET" },
  { "type": "ALERTA_ASISTENCIA", "label": "Alerta de Asistencia", "input": "DATASET" },
  { "type": "CARGA_ORACLE", "label": "Carga a Oracle (insertar y actualizar)", "input": "EXECUTION" },
  { "type": "LECTURA_ORACLE", "label": "Lectura desde Oracle", "input": "NONE" }
]

input dice qué debe enviar el formulario:

Valor Qué se envía en POST /api/executions
DATASET dataset: una carpeta de GET /api/datasets
EXECUTION sourceExecutionId: una ejecución de RENDIMIENTO_ACADEMICO en estado SUCCEEDED
NONE Nada más

GET /api/datasets

["con-errores", "limpio"]

Ejecuciones

POST /api/executions

Cuerpo:

{ "jobType": "CARGA_ORACLE", "dataset": null, "sourceExecutionId": "91b4edb1-ee70-4392-b37a-46d7eea1e108" }

Responde 202 con la ejecución (misma forma que un elemento de GET /api/executions), en estado RUNNING.

GET /api/executions

De la más reciente a la más antigua.

[
  {
    "id": "2863f42f-1842-4ad9-a85d-b16da73be0a4",
    "jobType": "RENDIMIENTO_ACADEMICO",
    "jobLabel": "Rendimiento académico",
    "status": "SUCCEEDED",
    "dataset": "con-errores",
    "sourceExecutionId": null,
    "startedAt": "2026-11-15T17:43:32.482Z",
    "finishedAt": "2026-11-15T17:43:58.120Z",
    "durationMs": 25638,
    "exitCode": 0
  }
]
status Significado
RUNNING El proceso de Spark sigue corriendo. finishedAt, durationMs y exitCode son null
SUCCEEDED Terminó bien
REJECTED La puerta de calidad bloqueó el lote (demasiadas filas rechazadas)
FAILED El proceso falló; el motivo está en el log

GET /api/executions/{id}

{
  "execution": { "id": "…", "jobType": "CARGA_ORACLE", "status": "SUCCEEDED", "…": "…" },
  "result": {
    "published": true,
    "rowsByTable": { "SEMESTRES": 6, "CURSOS": 9, "ESTUDIANTES": 120, "NOTAS": 4320, "ASISTENCIA": 17280, "RENDIMIENTO": 1080, "CURSOS_RESUMEN": 9 },
    "loads": [ { "table": "ESTUDIANTES", "inserted": 1, "updated": 119 } ],
    "totalRows": 22824,
    "insertedRows": 230,
    "updatedRows": 22594,
    "durationMs": 10344
  },
  "stages": []
}
  • result es null mientras el job no termina. Su forma depende del job:
    • CARGA_ORACLE: rowsByTable, loads (por tabla: inserted y updated), totalRows, insertedRows, updatedRows, durationMs.
    • LECTURA_ORACLE: rowsByTable, totalRows, durationMs.
    • RENDIMIENTO_ACADEMICO y ALERTA_ASISTENCIA: received, accepted, rejected, rejectedRatio, maxRejectedRatio, goldRows, durationMs.
  • stages solo tiene datos en los jobs de transformación. Cada elemento: stage (BRONZE, VALIDATION, QUARANTINE, SILVER, QUALITY_GATE, GOLD, EXPORT), status (RUNNING, COMPLETED, BLOCKED, SKIPPED, FAILED), timestamp, rows, durationMs, detail. Una etapa aparece dos veces (al empezar y al terminar): el frontend se queda con la última.

GET /api/executions/{id}/log

Texto plano con las últimas 200 líneas de la salida del proceso.

Calidad de datos

Solo existe en ejecuciones de RENDIMIENTO_ACADEMICO y ALERTA_ASISTENCIA.

GET /api/executions/{id}/quality

{
  "rulesVersion": "2.0.0",
  "received": 21759,
  "accepted": 21514,
  "rejected": 245,
  "rejectedRatio": 0.01126,
  "maxRejectedRatio": 0.05,
  "published": true,
  "decision": "Publicado: las filas válidas pasan a Gold y las observadas quedan en cuarentena",
  "tables": [
    { "table": "notas", "received": 4331, "accepted": 4265, "rejected": 66, "rejectedRatio": 0.015239, "withinTolerance": true }
  ],
  "dimensions": { "COMPLETITUD": 1, "VALIDEZ": 35, "UNICIDAD": 13, "INTEGRIDAD": 191, "CONSISTENCIA": 5 },
  "reasons": [
    { "table": "notas", "rule": "NOTA_FUERA_DE_RANGO", "dimension": "VALIDEZ", "description": "La nota esta fuera de la escala 0 a 20", "rows": 11 }
  ],
  "checks": [
    { "name": "Rechazo en notas", "passed": true, "detail": "66 de 4331 filas rechazadas (1.52 %); máximo 5.00 %" }
  ]
}
Campo Para qué sirve en la pantalla
received, accepted, rejected Filas que llegaron, las que se quedaron y las que no
rejectedRatio, maxRejectedRatio Porcentaje rechazado y el máximo que se tolera
published, decision Si el lote pasó la puerta de calidad y por qué
tables Lo mismo, por tabla
dimensions Rechazos por tipo de problema
reasons Cada regla incumplida: tabla, regla, descripción y cuántas filas
checks Los controles que deben cumplirse para publicar

Responde 404 si la ejecución no tiene reporte de calidad.

GET /api/executions/{id}/rejected

Las filas que no pasaron, con el motivo y el registro original tal como venía en el CSV.

[
  {
    "tabla": "asistencia",
    "fila": 1528,
    "clave": "VG260011 · EIA · 2026-II · 7",
    "motivos": ["ESTADO_INVALIDO"],
    "registro": { "estudiante_id": "VG260011", "curso_id": "EIA", "periodo": "2026-II", "semana": "7", "fecha": "2026-09-28", "estado": "X" }
  }
]

fila es el número de línea en el CSV de origen. motivos puede traer más de una regla. Si no hubo rechazos, devuelve [].

Dashboard (lee de Oracle)

GET /api/dashboard/performance

Una fila por estudiante y curso, de la tabla RENDIMIENTO.

[
  {
    "estudiante_id": "VG260041",
    "nombres": "Fabricio",
    "apellidos": "Aguilar Huertas",
    "seccion": "B",
    "curso_id": "APS",
    "curso": "Administración de Proyectos de Sistemas",
    "periodo": "2026-II",
    "promedio": 16.1,
    "nota_final": 16,
    "asistencia_pct": 1,
    "condicion": "APROBADO"
  }
]
  • asistencia_pct va de 0 a 1.
  • promedio y nota_final pueden ser null (matrícula con evaluaciones pendientes).
  • condicion: APROBADO, DESAPROBADO, INHABILITADO o PENDIENTE.

Con estas filas el frontend calcula los indicadores, los gráficos y los filtros por curso, sección, condición y estudiante.

GET /api/dashboard/courses

[
  {
    "curso_id": "APS",
    "curso": "Administración de Proyectos de Sistemas",
    "docente": "Mg. Carla Rojas Palomino",
    "periodo": "2026-II",
    "matriculados": 120,
    "aprobados": 101,
    "desaprobados": 19,
    "promedio": 15.27,
    "asistencia_promedio": 0.9335,
    "tasa_aprobacion": 0.8417
  }
]

GET /api/dashboard/tables

[
  { "tabla": "NOTAS", "filas": 4320, "ultima_carga": "2026-11-15T17:23:37.763412" }
]

ultima_carga es null si la tabla está vacía.

GET /api/dashboard/loads

Qué hizo cada ejecución del job de carga en cada tabla (tabla CARGAS), de la más reciente a la más antigua.

[
  { "ejecucion_id": "6283fedf-251e-4c67-be9d-40f7f5f613df", "tabla": "NOTAS", "filas_insertadas": 55, "filas_actualizadas": 4265, "fecha_carga": "2026-11-15T18:04:50.120000" }
]
  • filas_insertadas: filas que no existían y se crearon en esa carga.
  • filas_actualizadas: filas que ya existían (misma clave) y se volvieron a escribir.

El frontend agrupa por ejecucion_id para mostrar una carga a la vez.

Errores

Todos los errores tienen esta forma (ProblemDetail):

{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Elija un dataset de: [con-errores, limpio]", "instance": "/api/executions" }

El frontend muestra el campo detail.

Código Cuándo
400 Falta un dato o no es válido (job desconocido, dataset inexistente, ejecución de origen no válida, job sin compilar)
404 La ejecución no existe o no tiene reporte de calidad
503 No se pudo consultar Oracle
500 Error inesperado