Documentación de la API Externa (v1) - SmartTable

Esta documentación describe cómo interactuar con la API externa de SmartTable para consultar y procesar datos.

Autenticación

Todas las peticiones a esta API deben incluir una cabecera de autenticación x-api-key.

Cabecera Requerida:
x-api-key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves de API se pueden gestionar a través de la herramienta de línea de comandos del backend: node tools/manage-apikeys.js o solicitarlas a un admin.

Rate Limiting

La API actualmente no tiene límite de solicitudes por minuto, pero está en desarrollo. La API podría responder en un futuro con un código de estado 429 Too Many Requests.

Base URL

Todas las rutas de la API están prefijadas con:
/smarttable/external/v1

Endpoints

1. Health Check

Verifica que la API esté funcionando y que la autenticación sea correcta.

• Método: GET
• Ruta: /health-check
• Respuesta Exitosa (200 OK):

  {
    "success": true,
    "message": "External API is authenticated and running."
  }

2. Listar Datasets Disponibles

Obtiene una lista de los nombres de todos los datasets cargados en el servidor.

• Método: GET
• Ruta: /datasets
• Respuesta Exitosa (200 OK):

  {
    "success": true,
    "data": [
      "remedy_incidents",
      "remedy_changes",
      "otro_dataset"
    ]
  }

3. Obtener Contenido de un Dataset Específico

Recupera el contenido completo de un dataset utilizando su clave.

• Método: GET
• Ruta: /datasets/:datasetKey
• Parámetros de URL:
  • datasetKey (string, requerido): El nombre del dataset a consultar. Se puede obtener de la lista del endpoint /datasets.
• Respuesta Exitosa (200 OK):
  Devuelve el contenido del dataset, que típicamente es un array de objetos con una estructura de tabla.

  {
    "success": true,
    "data": [
      {
        "type": "table",
        "columns": [
          { "text": "Incident Number", "type": "string" },
          { "text": "Priority", "type": "string" }
        ],
        "rows": [
          ["INC001", "Critical"],
          ["INC002", "High"]
        ]
      }
    ]
  }

• Respuesta de Error (404 Not Found):
  Se devuelve si la datasetKey no corresponde a ningún dataset cargado.

  {
    "success": false,
    "error": "El dataset con la clave 'nombre_inexistente' no fue encontrado."
  }

Códigos de Error Comunes

• 401 Unauthorized: Falta la cabecera x-api-key o el token es inválido.
• 403 Forbidden: La x-api-key proporcionada es incorrecta.
• 400 Bad Request: El cuerpo de la petición es inválido (ej. JSON malformado, regla sin dataset).
• 404 Not Found: El recurso solicitado no existe (ej. un dataset especificado en una regla no se encuentra en el servidor).
• 500 Internal Server Error: Ocurrió un error inesperado en el servidor al procesar la petición.