HTTP API reference

In this document you can find description of various HTTP API endpoints that the Heimdall central manager provides.

Reload configuration

This endpoint allows for reload of Heimdall's configuration (heimdall.conf file).

Usage Example

Usage is pretty straightforward, just remember to authenticate the request. Curl pattern:

curl --user {username}:{password} http://{ipAddress}:{portNumber}/api/config/reload

Where:

Example command with default values on local Heimdall instance:

 curl --user admin:heimdall http://localhost:8087/api/config/reload   

Export VDB configuration

This endpoint allows for retrieval of selected properties of single VDB.

Usage Example

To effectively use this endpoint, provide a name of VDB to export and what should be extracted as request parameters. Call needs to be authenticated. Curl pattern:

curl --user {username}:{password} http://{ipAddress}:{portNumber}/api/config/{config}/export/{vdb}

Where:

Example command with default values on local Heimdall instance:

curl --user admin:heimdall http://localhost:8087/api/config/vdb/export/MySQLVirtualDatabase

Import VDB configuration

This endpoint allows for import of single VDB with all related properties (Data Sources, Drivers, Rules).

Usage Example

To use this endpoint, provide what should be imported as a {config} parameter. File with desired properties should also be provided. Call needs to be authorized too. Curl pattern:

curl --user {username}:{password} --form files=@{fileName} http://{ipAddress}:{portNumber}/api/config/import/{config}

Where:

Format of {fileName}
{
  "vdbs": [
    {
      "acCaseSensitiveFields": false, // defines if field names are case sensitive
      "acCaseSensitiveTables": false, // defines if tables names are case sensitive
      "accessType": "mysql", // is underlying dataBase: sqlsever, mysql, postgres
      "activecache": false, 
      "autotune": false,
      "cacheEnabled": false,
      "pciHipaaCache": false, // PCI/HIPAA compliant cache
      "cacheSize": 50000000, // size of cache in bytes
      "cacheSoftValues": true, // Determine use of soft references
      "cacheMaxExpiry": 0, // Maximum cache object age
      "cacheObjectCount": 0, // Maximum cache object count
      "cacheSizeRate": 1, // cache size unit rate
      "cacheType": "hazelcast", // type of cache
      "cloudMetrics": false, // determines if cloud specific metrics should be used
      "clusterCacheManager": false, // determines use of ClusterCacheManager
      "customkey": false, // false -> use vdb, catalog, user if true use custom cache key
      "debugMode": true, //debugMode for VDB
      "gridCacheName": "heimdall", // name of the cache to use
      "gridPort": 0, // grid cache port
      "databaseNumber": 0, // grid cache database number
      "id": 1606394877786, // config id
      "invalidationInterval": 500, // cache invalidation interval
      "jcacheClass": "com.hazelcast.cache.HazelcastCachingProvider", // class of Jcache driver
      "jdbcClass": "com.heimdalldata.HeimdallDriver", // class of JDBC driver
      "jdbcUrl": "jdbc:heimdall://\u003cHeimdall Server IP:port\u003e/MySQLVirtualDatabase?hduser\u003d\u003cuser\u003e\u0026hdpassword\u003d\u003cpassword\u003e",
      "keycatalog": true, // True if use database catalog as part of the hash key for query result cache
      "keyuser": true, // True if use database user as part of the hash key for query result cache
      "keyvdb": true, // True if use virtual database name as part of the hash key for query result cache
      "localCacheEnable": true,
      "localhostOnly": false, 
      "logConnections": true, // determines if Heimdall should log connections
      "loggingEnabled": true,
      "logMethods": false, // determines if method calls should be logged
      "logResultSetMethods": false, // determines if ResultSet method calls should be logged
      "logSelect": false, // determines if SQL SELECT method calls should be logged
      "logSql": true, // determines if SQL statements should be logged
      "mgmtProxyEnable": true, // determines if managment proxy should be enabled
      "tlsEnable": false,
      "tlsRequired": false,
      "ldapAuthEnabled": false,
      "delayedTransaction": false, // determines if delayed transactions should be enabled
      "paranoia": false, // determines paranoia mode, which when enabled logs much more information
      "multiplex": false, // determines if multiplexing should be enabled
      "multiplexTimeout": 0, 
      "trackQueryDistributionCount": 1000, // sets max number of queries to track
      "ldapGroupFilter": "", //ldap filter
      "ldapSimpleMode": false,
      "ldapPrefix": "",
      "ldapSuffix": "",
      "synchAuthentication": false, // determine if Authenticaton should be synchronized 
      "proxyauthEnabled": false, // determines if proxy authorization should be enabled
      "authMode": "proxy", // type of authorization: proxy, ldap, sql, passthrough
      "proxyAddress": "0.0.0.0", 
      "proxyPort": "3307",
      "xmx": 600, // max heap value for proxy
      "revalidateCache": false, // determines if cache revalidation should be enabled
      "secure": false, // is HTTPS on?
      "shipConsoleLogs": true, // determines if driver/proxy console logs should be sent to the server
      "useServer": false, // determines if server JVM should be in use
      "writeLogsToFile": false, // determines if logs should be written to file
      "sqlDrivenAuthEnabled": false, // should SQL Authorization be used?
      "authorizationQuery": "select * from heimdall.pg_hba where enabled \u003d true order by line_number asc", // query to use during SQL Authorization
      "accessKey": "HIBa3RN0BpDovDkP", // configuration accessKey
      "secretKey": "1nCAUUqnxqblJF74", // configuration secretKey
      "useSsl": false, // determines if SSL should be used
      "verifyPeer": false, // determines if SSL Certificate should be verified
      "jmxHostname": "${hostname}",
      "jmxPort": 0,
      "testSSL": false,
      "userCaseSensitive": false, // determines if username if case sensitive
      "enabled": true, // determines if VDB should be enabled
      "file": "config/MySQLVirtualDatabase_1.conf", // path to VBD configuration file
      "name": "MySQLVirtualDatabase", // name of VDB
      "version": 1, // version of VDB configuration
      "dataSources": [ // array of Data Sources associated with VDB
        {
          "enabled": true, // determines if Data Source should be enabled
          "file": "config/MySQLDataSource_4.conf", // path to Data Source configuration file
          "name": "MySQLDataSource", // name of Data Source
          "version": 4 // version of Data Source configuration
        }
      ],
      "rules": [ // rules associated with VDB
        {
          "enabled": true, // determines if Rules should be enabled
          "file": "config/RulesForAll_1.conf", // path to Rules configuration file
          "name": "RulesForAll", // name of Rules
          "version": 1 // version of Rules configuration
        }
      ],
      "properties": [ // properties associated with VDB
        {
          "key": "",
          "value": ""
        }
      ],
      "users": [ // underlying database credentials
        {
          "user": "root",
          "password": "password"
        }
      ],
      "pinnedClients": [], // array of pinned clients
      "modules": [ // array of Heimdall jars
        "modules/heimdallloadbalancer-1.0-20.11.26.1.jar",
        "modules/heimdallredis-5.3.0-20.11.26.1.jar",
        "modules/heimdallforward-1.0-20.11.26.1.jar",
        "modules/heimdallmysql-1.0-20.11.26.1.jar",
        "modules/heimdallsqlserver-1.0-20.11.26.1.jar",
        "modules/heimdallpostgres-1.0-20.11.26.1.jar",
        "modules/heimdalltrigger-1.0-20.11.26.1.jar",
        "modules/heimdallauth-1.0-20.11.26.1.jar",
        "modules/heimdallhazelcast-3.6.8-20.11.26.1.jar",
        "modules/heimdallextractplan-1.0-20.11.26.1.jar",
        "modules/heimdallfirewall-1.0-20.11.26.1.jar",
        "modules/heimdallasync-1.0-20.11.26.1.jar",
        "modules/heimdallaws-1.0-20.11.26.1.jar"
      ]
    }
  ],
  "sources": [ // Data Source configuration associated with VDB
    {
      "url": "jdbc:mysql://localhost:3306/myDb?allowPublicKeyRetrieval\u003dtrue\u0026useSSL\u003dfalse", // Data Source JDBC url
      "driverConfig": { 
        "enabled": true, // determines if Driver associated with Data Source is enabled
        "file": "config/MySQLDriver_1.conf", // path to Driver's configuration file
        "name": "MySQLDriver", // name of Driver
        "version": 1 // version of Driver configuration
      },
      "driverClass": "com.mysql.jdbc.Driver", // class of JDBC Driver
      "driverUrl": "/drivers/MySQLDriver/mysql-connector-java-5.1.49.jar", // path to JDBC Driver
      "properties": {
        "user": "root", // database user
        "password": "password", // database password
        "url": "jdbc:mysql://localhost:3306/myDb?allowPublicKeyRetrieval\u003dtrue\u0026useSSL\u003dfalse", // database url
        "testQuery": "SELECT 1"
      },
      "usepool": false, //determines if connection pooling should be used
      "poolProperties": {}, // key-value object of connection pooling properties
      "servers": [ // array of Data Surce Servers configurations associated with Data Source
        {
          "name": "Primary", // server name
          "url": "jdbc:mysql:// localhost:3306/myDb?allowPublicKeyRetrieval=true&useSSL=false", // server JDBC url
          "enabled": true, 
          "writeable": true, // true for master, false for slave
          "weight": 1, // relative amount of load server can handle
          "readWeight": 1, // read weight for server
          "writeWeight": 1, // write weight for server
          "active": true,
          "failed": true,
          "maxLag": 2147483647 
        }
      ],
      "useLoadBalancing": true,
      "trackClusterChanges": false,
      "desiredWriteCapacity": 1, // desired write capacity for all writeable nodes
      "desiredReadCapacity": 10, // desired read capacity
      "trackReplicationLags": true,
      "timeWindow": 10000, // safe window for replication lag in ms
      "useMonitoring": false, // determines if server monitoring should be enabled
      "holdTime": 30000, // time to hold connections/operations waiting for valid server to be available
      "obscure": {
        "secretKey": "Odrv3jRI9sliFSZUFXwbynSf68Llbi" // key to obscure password with
      },
      "enabled": true, // determines if Data Source should be enabled
      "file": "config/MySQLDataSource_4.conf", // path to Data Source configuration file
      "name": "MySQLDataSource", // name of Data Source
      "version": 4 // version of Data Source configuration
    }
  ],
  "drivers": [ // array with Drivers associated with VDB
    {
      "jdbcClass": "com.mysql.jdbc.Driver", // JDBC Driver class
      "uploadedDrivers": [
        "/drivers/MySQLDriver/mysql-connector-java-5.1.49.jar" // path to Driver
      ],
      "autoUpdate": true,
      "enabled": true, // determines if Driver should be enabled
      "file": "config/MySQLDriver_1.conf", // path to Driver configuration file
      "name": "MySQLDriver", // name of Driver
      "version": 1 // version of Driver configuration
    }
  ],
  "rules": [ // array with Rules associated with VDB
    {
      "rules": [
        {
          "enabled": true, // determines if Rule should be enabled
          "type": "C", // type of rule, description below
          "patterns": [ // array with regex patterns for rule
            ""
          ],
          "intrans": false, // determines if Rule can be aplied whithin transacion
          "properties": { // key-value parameters of Rule
            "ttl": "5*60000"
          }
        },
        {
          "enabled": true, // determines if Rule should be enabled
          "type": "C", // type of rule, description below
          "patterns": [ // array with regex patterns for rule
            ""
          ],
          "intrans": true, // determines if Rule can be aplied whithin transacion
          "properties": { // key-value parameters of Rule
            "ttl": "5*60000"
          }
        },
        {
          "enabled": true, // determines if Rule should be enabled
          "type": "V", // type of rule, description below
          "patterns": [ // array with regex patterns for rule
            "(?i)^select"
          ],
          "intrans": false, // determines if Rule can be aplied whithin transacion
          "properties": { // key-value parameters of Rule
            "lagignore": "false"
          }
        }
      ],
      "enabled": true, // determines if Rules should be enabled
      "file": "config/RulesForAll_1.conf", // path to Rules configuration file
      "name": "RulesForAll", // name of Rules
      "version": 1 // version of Rules configuration
    }
  ]
}
Rule Types
Q -> allow
A -> async execute
C -> cache
G -> call
Z -> debug
D -> drop
O -> extract plan
F -> forward
I -> ignore
P -> learn pattern
L -> log
B -> nocache
M -> pool
V -> reader eligible
N -> result
E -> retry
S -> stack trace
W -> table cache
X -> tag
T -> transform
R -> trigger

Example command with default values on local Heimdall instance:

curl --user admin:heimdall --form files=@file.json  http://localhost:8087/api/config/import/vdb 

Export Data Source Servers configuration

This endpoint allows for retrieving Data Source Servers configuration by name.

Usage Example

Provide a name of existing VDB and credentials. Curl pattern:

curl --user {username}:{password} http://{ipAddress}:{portNumber}/api/config/source/{name}/servers

Where:

Example command with default values on local Heimdall instance:

curl --user admin:heimdall http://localhost:8087/api/config/source/MySQLDataSource/servers

Import Data Source Servers configuration

This endpoint allows for creating new Data Source Server configuration in existing Data Source.

Usage Example

Provide a name of existing VDB and new Data Source Server properties, to update it. This endpoint is secured, so we have to use authentication. Request must have Header of content-type set to application/json. Curl pattern:

curl --user {username}:{password} --data-binary @{filename} -H "Content-Type: application/json" http://{ipAddress}:{portNumber}/api/config/source/{name}/servers

Where:

Format of {filename}:

    [ 
        {
          "name": "Primary", // server name
          "url": "jdbc:mysql:// localhost:3306/myDb?allowPublicKeyRetrieval=true&useSSL=false", // server JDBC url
          "enabled": true, 
          "writeable": true, // true for master, false for slave
          "weight": 1, // relative amount of load server can handle
          "readWeight": 1, // read weight for server
          "writeWeight": 1, // write weight for server
          "active": true,
          "failed": true,
          "maxLag": 2147483647 
        }
    ]

Example command with default values on local Heimdall instance:

curl -v --output - --user admin:heimdall --data-binary @file.json -H "Content-Type: application/json"  http://localhost:8087/api/config/source/MySQLDataSource/servers