API Reference

JSON-RPC 2.0 Protocol

Fracttal ETL Hub implements the JSON-RPC 2.0 protocol for all ETL operations. All requests must follow this structure:

Request Structure

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

Required Fields

Field	Type	Description
jsonrpc	string	Protocol version. Must be "2.0"
method	string	Method to execute. Currently only "etl.etl_update"
params	object	Method parameters
id	string	Unique request identifier

etl.etl_update Method

Description

Executes a complete ETL configuration with source, transformation, and target.

Parameters

params.id

• Type: string
• Description: Unique identifier for the ETL configuration
• Required: ✅
• Example: "config-001"

params.config

• Type: object
• Description: Complete ETL configuration
• Required: ✅

params.config.source

• Type: object
• Description: Data source configuration
• Required: ✅

params.config.transform

• Type: object
• Description: Data transformation configuration
• Required: ❌

params.config.target

• Type: object
• Description: Data target configuration
• Required: ✅

params.environment

• Type: string
• Description: Execution environment
• Values: "production", "develop"
• Required: ✅
• Default: "develop"

Success Response

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

Error Response

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

Validation Schemas

Connections

Each connection type has its own validation schema defined in Pydantic models. Schemas are automatically validated before execution.

Operations

Available operations depend on the connection type and are defined in the JSON configuration files.

Transformations

Transformations follow JSON Logic syntax with additional custom operators.

Error Codes

Code	Description
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32000	Server error

Complete Examples

Basic ETL

{
  "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 with Transformation

{
  "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"}, "name", "string"],
          [{"var": "last_name"}, "surname", "string"]
        ],
        "add": [
          [{"var": "name"}, " ", {"var": "surname"}, "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"
}