Referência da API

Protocolo JSON-RPC 2.0

Fracttal ETL Hub implementa o protocolo JSON-RPC 2.0 para todas as operações ETL. Todas as solicitações devem seguir esta estrutura:

Estrutura da Solicitação

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

Campos Obrigatórios

Campo	Tipo	Descrição
jsonrpc	string	Versão do protocolo. Deve ser "2.0"
method	string	Método a executar. Atualmente apenas "etl.etl_update"
params	object	Parâmetros do método
id	string	Identificador único da solicitação

Método etl.etl_update

Descrição

Executa uma configuração ETL completa com origem, transformação e destino.

Parâmetros

params.id

• Tipo: string
• Descrição: Identificador único da configuração ETL
• Obrigatório: ✅
• Exemplo: "config-001"

params.config

• Tipo: object
• Descrição: Configuração completa do ETL
• Obrigatório: ✅

params.config.source

• Tipo: object
• Descrição: Configuração da origem de dados
• Obrigatório: ✅

params.config.transform

• Tipo: object
• Descrição: Configuração de transformação de dados
• Obrigatório: ❌

params.config.target

• Tipo: object
• Descrição: Configuração do destino de dados
• Obrigatório: ✅

params.environment

• Tipo: string
• Descrição: Ambiente de execução
• Valores: "production", "develop"
• Obrigatório: ✅
• Padrão: "develop"

Resposta de Sucesso

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

Resposta de Erro

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

Esquemas de Validação

Conexões

Cada tipo de conexão tem seu próprio esquema de validação definido nos modelos Pydantic. Os esquemas são validados automaticamente antes da execução.

Operações

As operações disponíveis dependem do tipo de conexão e são definidas nos arquivos de configuração JSON.

Transformações

As transformações seguem a sintaxe JSON Logic com operadores customizados adicionais.

Códigos de Erro

Código	Descrição
-32700	Erro de análise
-32600	Solicitação inválida
-32601	Método não encontrado
-32602	Parâmetros inválidos
-32603	Erro interno
-32000	Erro do servidor

Exemplos 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 com Transformação

{
  "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"}, "nome", "string"],
          [{"var": "last_name"}, "sobrenome", "string"]
        ],
        "add": [
          [{"var": "nome"}, " ", {"var": "sobrenome"}, "nome_completo", "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"
}