HTTP API reference
In this document you can find description of various HTTP API endpoints that the Heimdall central manager provides.
Reload configuration
- Endpoint URL: api/config/reload
- HTTP Method: GET (Preferred, It takes all types of methods)
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:
- {username} -> Heimdall's username
- {password} -> Heimdall's password
- {ipAddress} -> Heimdall's IP or DNS name
- {portNumber} -> Heimdall's server port number
Example command with default values on local Heimdall instance:
curl --user admin:heimdall http://localhost:8087/api/config/reload
Export VDB configuration
- Endpoint URL: api/config/{config}/export/{vdb}
- HTTP Method: GET
-
Parameters:
- {config}: String value that controls what is being returned by this endpoint in JSON:
- "vdb" -> returns whole VDB configuration (current VDB, Data Sources, Drivers, Rules)
- "source" -> returns Data Sources and Drivers related to VDB
- "driver" -> returns Drivers related to VDB
- "policy" -> returns Rules related to VDB
- {vdb}: Name of VDB which details should be exposed
- {config}: String value that controls what is being returned by this endpoint in JSON:
-
Response Body: JSON file with chosen properties
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:
- {username} -> Heimdall's username
- {password} -> Heimdall's password
- {ipAddress} -> Heimdall's IP or DNS name
- {portNumber} -> Heimdall's server port number
- {config} -> string value determining what's exported (described above)
- {vdb} -> name of VDB to export
Example command with default values on local Heimdall instance:
curl --user admin:heimdall http://localhost:8087/api/config/vdb/export/MySQLVirtualDatabase
Import VDB configuration
- Endpoint URL: api/config/import/{config}
- HTTP Method: POST
- Parameters:
- {config}: String value that controls what is being imported:
- "vdb" -> updates all VBD properties
- "source" -> updates Data Sources of VDB
- "driver" -> updates Drivers of VDB
- "policy" -> updates Rules of VDB
- {config}: String value that controls what is being imported:
- Request Body: JSON file with properties of VDB
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:
- {username} -> Heimdall's username
- {password} -> Heimdall's password
- {fileName} -> file with VDB properties to import
- {ipAddress} -> Heimdall's IP or DNS name
- {portNumber} -> Heimdall's server port number
- {config} -> string value determining what's imported (described above)
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
"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
"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",
"excludeKeyCatalog": false, // True if exclude catalog part of the hash key for query result cache
"excludeKeySchema": false, // True if exclude schema part of the hash key for query result cache
"excludeKeySqlComments": false, // True if exclude sql comments part of the hash key for query result cache
"excludeKeyUser": false, // True if exclude connected database user part of the hash key for query result cache
"excludeKeyVdb": false, // True if exclude virtual database name 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
"logSql": true, // determines if SQL statements should be logged
"logAuthentications": false, // determines if authentication 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
"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
- Endpoint URL: api/config/source/{name}/servers
- HTTP Method: GET
- Parameters:
- {name}: Name of Data Source Servers to export
- Response Body: JSON file with list of Data Source Servers Properties.
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:
- {username} -> Heimdall's username
- {password} -> Heimdall's password
- {ipAddress} -> Heimdall's IP or DNS name
- {portNumber} -> Heimdall's server port number
- {name} -> name of existing Data Source
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
- Endpoint URL: api/config/source/{name}/servers
- HTTP Method: POST
- Parameters:
- {name}: Name of Data Source to import Data Source Servers configuration to
- Request Body: JSON file with list of Data Source Servers Properties.
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:
- {username} -> Heimdall's username
- {password} -> Heimdall's password
- {filename} -> name of file with DataSourceServer properties
- {ipAddress} -> Heimdall's IP or DNS name
- {portNumber} -> Heimdall's server port number
- {name} -> name of existing DataSource
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