API Reference

Protocolo JSON-RPC 2.0

Fracttal ETL Hub implementa el protocolo JSON-RPC 2.0 para todas las operaciones ETL. Todas las solicitudes deben seguir esta estructura:

Estructura de Solicitud

{
  "jsonrpc": "2.0",
  "method": "string",
  "params": {
    "id": "string",
    "config": {
      "source": {...},
      "transform": {...},
      "target": {...}
    },
    "environment": "production" | "develop"
  },
  "id": "string"
}

Campos Requeridos

Campo	Tipo	Descripción
jsonrpc	string	Versión del protocolo. Debe ser "2.0"
method	string	Método a ejecutar. Actualmente solo "etl.etl_update"
params	object	Parámetros del método
id	string	Identificador único de la solicitud

Método etl.etl_update

Descripción

Ejecuta una configuración ETL completa con origen, transformación y destino.

Parámetros

params.id

• Tipo: string
• Descripción: Identificador único de la configuración ETL
• Requerido: ✅
• Ejemplo: "config-001"

params.config

• Tipo: object
• Descripción: Configuración completa del ETL
• Requerido: ✅

params.config.source

• Tipo: object
• Descripción: Configuración del origen de datos
• Requerido: ✅

params.config.transform

• Tipo: object
• Descripción: Configuración de transformación de datos
• Requerido: ❌

params.config.target

• Tipo: object
• Descripción: Configuración del destino de datos
• Requerido: ✅

params.environment

• Tipo: string
• Descripción: Entorno de ejecución
• Valores: "production", "develop"
• Requerido: ✅
• Por defecto: "develop"

Respuesta Exitosa

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "execution_id": "exec-12345",
    "message": "ETL executed successfully"
  },
  "id": "request-001"
}

Respuesta de Error

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Validation error details"
    }
  },
  "id": "request-001"
}

Esquemas de Validación

Conexiones

Cada tipo de conexión tiene su propio esquema de validación definido en los modelos Pydantic. Los esquemas se validan automáticamente antes de la ejecución.

Operaciones

Las operaciones disponibles dependen del tipo de conexión y están definidas en los archivos JSON de configuración.

Transformaciones

Las transformaciones siguen la sintaxis JSON Logic con operadores custom adicionales.

Códigos de Error

Código	Descripción
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32000	Server error

Ejemplos Completos

ETL Básico

{
  "jsonrpc": "2.0",
  "method": "etl.etl_update",
  "params": {
    "id": "etl-basic-001",
    "config": {
      "source": {
        "connection": {
          "id_type": 9,
          "name": "PostgreSQL",
          "parameters": {
            "host": "localhost",
            "port": 5432,
            "database": "mydb",
            "username": "user",
            "password": "pass"
          }
        },
        "operation": "select",
        "parameters": {
          "query": "SELECT * FROM users WHERE active = true"
        }
      },
      "target": {
        "connection": {
          "id_type": 3,
          "name": "Google Sheets",
          "parameters": {
            "spreadsheet_id": "123456789",
            "credentials_file": "/path/to/creds.json"
          }
        },
        "operation": "append",
        "parameters": {
          "sheet_name": "Users"
        }
      }
    },
    "environment": "production"
  },
  "id": "req-001"
}

ETL con Transformación

{
  "jsonrpc": "2.0",
  "method": "etl.etl_update",
  "params": {
    "id": "etl-transform-001",
    "config": {
      "source": {
        "connection": {
          "id_type": 9,
          "name": "PostgreSQL",
          "parameters": {
            "host": "localhost",
            "port": 5432,
            "database": "mydb",
            "username": "user",
            "password": "pass"
          }
        },
        "operation": "select",
        "parameters": {
          "query": "SELECT id, first_name, last_name, email FROM users"
        }
      },
      "transform": {
        "rename": [
          [{"var": "first_name"}, "nombre", "string"],
          [{"var": "last_name"}, "apellido", "string"]
        ],
        "add": [
          [{"var": "nombre"}, " ", {"var": "apellido"}, "full_name", "string"]
        ]
      },
      "target": {
        "connection": {
          "id_type": 3,
          "name": "Google Sheets",
          "parameters": {
            "spreadsheet_id": "123456789",
            "credentials_file": "/path/to/creds.json"
          }
        },
        "operation": "append",
        "parameters": {
          "sheet_name": "Users"
        }
      }
    },
    "environment": "production"
  },
  "id": "req-002"
}