Documentación de la API de Ingesta - SmartTable

Esta documentación describe cómo utilizar la API de ingesta para enviar datasets al servidor de SmartTable de forma programática.

1. Endpoint Principal

La ingesta de datos se realiza a través de un único endpoint POST.

Parámetros

Parámetro Tipo Descripción
:schemaName Path (String) Obligatorio. El nombre del esquema que valida el payload. Actualmente, el único valor soportado es remedy.
:datasetName Path (String) Obligatorio. El nombre único que identificará al dataset en el sistema. Este nombre se usará para el archivo y para referenciarlo en los paneles.
?writeMode Query (String) Opcional. Especifica el modo de escritura. Si se omite, el valor por defecto es overwrite.
- overwrite: Sobrescribe el archivo del dataset. Crea un archivo .json.
- append: Añade los datos como una nueva línea. Crea un archivo .jsonl.

2. Autenticación

Todas las peticiones a este endpoint deben estar autenticadas mediante una API Key.

Las claves se crean y gestionan en la consola del servidor utilizando el script tools/manage-apikeys.js. Solicitar creación a un administrador.

3. Esquema de Datos: remedy

Para el schemaName remedy, el cuerpo de la petición (body) debe ser un JSON que cumpla estrictamente con la siguiente estructura y reglas.

Ejemplo de Payload Válido

[
  {
    "columns": [
      { "text": "Incident Number", "type": "string" },
      { "text": "Submit Date", "type": "date" },
      { "text": "Status", "type": "string" }
    ],
    "rows": [
      [ "INC00001", "2023-10-27T10:00:00Z", "Assigned" ],
      [ "INC00002", "2023-10-27T11:30:00Z", "In Progress" ],
      [ "INC00003", "2023-10-27T12:00:00Z", "Pending" ]
    ],
    "type": "table"
  }
]

Reglas y Restricciones del Esquema

4. Ejemplos de Peticiones (curl)

Asegúrate de reemplazar <TU_API_KEY> con una clave válida y activa.

Ejemplo 1: Sobrescribir un Dataset

Este comando enviará un dataset completo, creando o reemplazando el archivo incidents_daily_report.json.

# URL: /smarttable/ingest/remedy/incidents_daily_report
# Modo: overwrite (por defecto)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <TU_API_KEY>" \
  -d '[{"columns":[{"text":"Incident Number","type":"string"},{"text":"Status","type":"string"}],"rows":[["INC001","Assigned"],["INC002","Resolved"]],"type":"table"}]' \
  http://<IP-SERVIDOR[:PUERTO]>/smarttable/ingest/remedy/incidents_daily_report

Ejemplo 2: Añadir Datos a un Log (Modo append)

Este comando añadirá los datos de un nuevo incidente a un archivo de registro, creando incident_log.jsonl si no existe.

# URL: /smarttable/ingest/remedy/incident_log?writeMode=append
# Modo: append (explícito)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <TU_API_KEY>" \
  -d '[{"columns":[{"text":"Incident Number","type":"string"},{"text":"Status","type":"string"}],"rows":[["INC003","Pending"]],"type":"table"}]' \
  "http://<IP-SERVIDOR[:PUERTO]>/smarttable/ingest/remedy/incident_log?writeMode=append"

5. Códigos de Respuesta de la API

Código Significado Descripción Detallada
201 Created Éxito Los datos fueron recibidos, validados y guardados correctamente en el disco del servidor.
400 Bad Request Error del Cliente La petición es inválida. Causas comunes: un schemaName o writeMode no soportado, o un body JSON que no cumple con las reglas del esquema. La respuesta incluirá un campo details con los errores específicos.
401 Unauthorized Fallo de Autenticación La petición no incluyó la cabecera X-API-KEY.
403 Forbidden Acceso Denegado La X-API-KEY proporcionada existe pero es incorrecta, o su estado es inactive.
500 Internal Server Error Error del Servidor Ocurrió un error inesperado en el servidor durante el procesamiento, como un fallo de permisos al escribir el archivo. Revisa los logs del servidor para más detalles.

6. Notas Importantes y Buenas Prácticas