Catálogo de la API REST

Convenciones generales

  • Versión en la URL: todas las rutas comienzan con /api/0.6.9/. La versión sigue semver (VERSION) y se complementa con el hash git en los healthchecks.
  • Estructura RESTful: /api/<version>/<colección>/<recurso>/<subcolección>/<subrecurso>?filters=&sort=&page=&page_size=.
  • Formato de respuesta: JSON envolviendo data y meta.
  • Códigos HTTP:
    • 200: respuesta exitosa.
    • 404: recurso no disponible.
    • 422: parámetros inválidos.
    • 500: error interno.
  • Cache: respuestas GET se cachean en memoria (TTL configurable vía API_CACHE_TTL_SECONDS).
  • OpenAPI: disponible en /api/0.6.9/openapi.json y UI interactiva en /api/0.6.9/docs.

Endpoints principales

Endpoint Descripción Ejemplo
GET /datasets Lista todo el catálogo registrado en data/meta/catalog/ /api/0.6.9/datasets
GET /datasets/{slug} Devuelve la ficha completa del dataset /api/0.6.9/datasets/epdatos
GET /datasets/{tabla} Extrae datos tabulares desde Postgres (dimensiones/seeds) /api/0.6.9/datasets/dim_region?page=1&page_size=25
GET /datasets/{slug}/{subcolección} Obtiene secciones del dataset (e.g. esquema, dominios) /api/0.6.9/datasets/epdatos/esquema
GET /datasets/{slug}/{subcolección}/{id} Selecciona un elemento puntual /api/0.6.9/datasets/epdatos/dominios/geografia
GET /datasets/{slug}/raw-assets Lista el inventario raw (manifest DIPRES) con descargas directas /api/0.6.9/datasets/dipres_ejecucion_total/raw-assets?limit=50
GET /data/{schema.table} Consulta una tabla con filtros/paginación y linaje meta /api/0.6.9/data/bronze.dipres_presupuestos_totales?columns=slug,moneda
GET /datasets/dipres_presupuestos Ficha del dataset DIPRES con descargas + esquema bronze /api/0.6.9/datasets/dipres_presupuestos
GET /health Estado del API (readiness) /api/0.6.9/health
GET /status Métricas, cobertura DIPRES y últimos payloads /api/0.6.9/status
GET /presupuestos Lista de presupuestos normalizados (silver) /api/0.6.9/presupuestos
GET /presupuestos/{slug} Detalle y totales agregados del presupuesto /api/0.6.9/presupuestos/ejecucion_total-ejecucion-2024-enero
GET /presupuestos/{slug}/partidas Jerarquía nivel Partidas (filtros/paginación) /api/0.6.9/presupuestos/ejecucion_total-ejecucion-2024-enero/partidas?filters=codigo:10
GET /presupuestos/{slug}/partidas/{codigo}/capitulos/... Navegación recursiva hasta asignaciones /api/0.6.9/presupuestos/{slug}/partidas/{codigo}/capitulos/{codigo}/programas
GET /presupuestos/stats Métricas agregadas y variaciones interanuales /api/0.6.9/presupuestos/stats?nivel=partida&aggregate=true

Las colecciones permitidas actualmente son datasets. Nuevas colecciones deben declararse en ALLOWED_TABLES o ampliar la lógica en api/routes/catalog.py.

Referencias macroeconómicas (BCCh)

Las series IPC/PIB descargadas a través de scripts/fetch_bcch_series.py viven en data/ref/bcch/. Aún no se exponen como endpoints públicos, pero la API reconoce el catálogo ref_bcch:

Endpoint Descripción Ejemplo
GET /datasets/ref_bcch Ficha del paquete BCCh (IPC y PIB) /api/0.6.9/datasets/ref_bcch
GET /datasets/ref_bcch/schema Esquema de tablas de referencia /api/0.6.9/datasets/ref_bcch/schema

Si necesitas exponer datos tabulares directamente (/datasets/ref_bcch/bcch_ipc_mensual), agrega la tabla a ALLOWED_TABLES o crea endpoints dedicados (aún pendiente).

Parámetros soportados

  • filters: repetible, formato campo:valor. Sólo campos permitidos por tabla (api/routes/catalog.py::ALLOWED_TABLES).
  • sort: columna para ordenar.
  • order: asc (default) o desc.
  • page: entero ≥ 1.
  • page_size: 1–200.

Para /presupuestos:

  • filters: permite codigo y nombre en cada nivel. Se aceptan múltiples valores (?filters=codigo:10&filters=nombre:MINISTERIO).
  • sort: codigo, nombre, monto_inicial_clp, monto_ejecutado_clp.
  • order, page, page_size igual que datasets.

Para /datasets/{slug}/raw-assets:

  • year: año específico (>= 1999).
  • period: período exacto (enero, marzo, primer_trimestre, anual, etc.).
  • currency: pesos o dolares según manifest.
  • format: filtra por extensión (csv, xls, xlsx, xml, pdf).
  • limit: cantidad de filas a devolver (1–500, default 200).
  • offset: desplazamiento para paginar.

Endpoint /presupuestos/stats:

  • nivel (obligatorio): partida, capitulo, programa, subtitulo, item o asignacion (plural también aceptado).
  • path: ruta jerárquica partida/capitulo/... para fijar el contexto.
  • instrumento, tipo, slug: filtros directos sobre el presupuesto.
  • moneda: filtra por moneda original (pesos, dolares). Para totales en CLP dejar vacío o clp (las columnas _clp siempre vienen convertidas).
  • anio_desde, anio_hasta: rango de años.
  • aggregate=true: agrupa y suma montos por año y códigos.
  • include_variacion=true: agrega columnas delta_* comparando con el año anterior (no combinable con aggregate).
  • Si las vistas vw_presupuesto_* no están disponibles (p.ej. entorno local sin Postgres), la API se apoya en el manifiesto CSV y calcula las métricas en memoria.

Payloads de presupuestos

  • Cada nodo (partidas, capitulos, etc.) entrega montos normalizados:
  • monto_*_clp: valores en pesos chilenos (CLP) transformados con el tipo de cambio oficial.
  • monto_*_mo: moneda original (pesos o dolares) en las mismas unidades publicadas por DIPRES.
  • naturaleza: clasificación presupuestaria (ingreso, gasto, mixto, desconocido) según el subtítulo DIPRES.
  • unidad: bloque con el factor aplicado (factor_multiplicado = 1) y la lista de monedas presentes; evita que se vuelva a escalar accidentalmente.
  • Las respuestas agregadas (/presupuestos/stats) incluyen en meta.unidad la descripción de campos CLP vs. moneda original y el nombre del campo naturaleza.

Ejemplo con filtros:

GET /api/0.6.9/datasets/dim_region?filters=region_id:1&sort=orden&order=asc&page=1&page_size=10

Los datasets que apuntan a DIPRES (dipres_ejecucion_total, dipres_proyecto_ley, dipres_ley_presupuesto y dipres_presupuestos) incluyen en su respuesta un bloque raw_assets con:

  • summary: totales, años, monedas y formatos detectados en el manifest.
  • endpoint: URL del inventario raw (/datasets/{slug}/raw-assets).

Convenciones del catálogo (data/meta/catalog/*.yaml)

Campo Descripción
slug Identificador del dataset (usado en rutas)
nombre Nombre legible
descripcion Texto corto
origen Fuente, URL, periodicidad
capas Información raw/bronze/silver/gold
dominios Temas o dominios asociados al dataset
esquema Lista de tablas y campos
lineaje Información de linaje raw → gold
contacto Persona o equipo responsable

El API expone estas estructuras tal cual se definen, permitiendo explorar catálogos y trazabilidad.

Buenas prácticas al agregar endpoints

  1. Añadir definición al catálogo (YAML) y actualizar ALLOWED_TABLES o repositorio SQL.
  2. Documentar el uso en este archivo (nueva tabla en la sección Endpoints).
  3. Agregar pruebas en tests/api/ cubriendo casos base y errores.
  4. Propagar métricas: usar JSONResponse y setear payload_meta para que el middleware registre actividad.
Volver arriba