REST API
As you use Visual DB, you create artifacts such as queries, form specifications, and report specifications. These artifacts can be downloaded from and uploaded to Visual DB programmatically using its REST API. This allows you to store them in a version control system or to migrate them between Visual DB’s SaaS environment and a self-hosted deployment.
Authentication
All API requests require authentication using an API key.
Authentication is performed using a Bearer token in the Authorization header
Example: Authorization: Bearer your-api-key-here
API keys are specific to an application (identified by appId)
To get the API key go to your application’s Home screen and click on the configuration link. The configuration dialog displays the App id and API key, both of which are needed to use the REST API.
Quick Start
Here’s a quick example to fetch a connection specification:
curl -H "Authorization: Bearer {apiKey}"
https://app.visualdb.com/public/api/apps/{appId}/artifacts/connections/SalesDatabase
This example downloads the specification of your SalesDatabase connection. Replace {apiKey}
with your API key and {appId}
with your appId.
List Connections
GET /public/api/apps/{appId}/artifacts/connections
Returns a list of all connections in the specified application with their names and types.
Get Connection Details
GET /public/api/apps/{appId}/artifacts/connections/{connectionName}
Returns details of a specific connection. Note that for security reasons, the password is always redacted.
Create Connection
POST /public/api/apps/{appId}/artifacts/connections/{connectionName}
Creates a new connection. The request body should be a JSON object with the following properties:
connectionName
The name of the connection
providerName
The database provider type. Must be one of: POSTGRES, MYSQL, SQL (for SQL Server) or ORACLE.
connectionString
The connection string. Must not contain secrets such as password.
userName
Database username
password
Database password
Delete Connection
DELETE /public/api/apps/{appId}/artifacts/connections/{connectionName}
Deletes a specific connection. The operation will fail if the connection is referenced by any queries. The response will include the names of the dependent queries if deletion fails due to dependencies.
List Queries
GET /public/api/apps/{appId}/artifacts/queries
Returns a list of all queries in the specified application with their names and associated connection names.
Get Query Details
GET /public/api/apps/{appId}/artifacts/queries/{queryName}
Returns the full specification of a specific query.
Update Query Connection
PATCH /public/api/apps/{appId}/artifacts/queries/{queryName}/connection
Updates the connection associated with a specific query. The request body should be a string containing the name of the new connection to associate with the query. The connection must exist in the application.
Delete Query
DELETE /public/api/apps/{appId}/artifacts/queries/{queryName}
Deletes a specific query. The operation will fail if the query is referenced by any forms, sheets, or reports. The response will include the names of the dependent artifacts if deletion fails due to dependencies.
List Forms
GET /public/api/apps/{appId}/artifacts/forms
Returns a list of all forms in the specified application with their names and associated query names.
Get Form Details
GET /public/api/apps/{appId}/artifacts/forms/{formName}
Returns the full specification of a specific form.
Update Form Query
PATCH /public/api/apps/{appId}/artifacts/forms/{formName}/query
Updates the query associated with a specific form. The request body should be a string containing the name of the new query to associate with the form. The query must exist in the application.
Delete Form
DELETE /public/api/apps/{appId}/artifacts/forms/{formName}
Deletes a specific form.
List Sheets
GET /public/api/apps/{appId}/artifacts/sheets
Returns a list of all sheets in the specified application with their names and associated query names.
Get Sheet Details
GET /public/api/apps/{appId}/artifacts/sheets/{sheetName}
Returns the full specification of a specific sheet.
Update Sheet Query
PATCH /public/api/apps/{appId}/artifacts/sheets/{sheetName}/query
Updates the query associated with a specific sheet. The request body should be a string containing the name of the new query to associate with the sheet. The query must exist in the application.
Delete Sheet
DELETE /public/api/apps/{appId}/artifacts/sheets/{sheetName}
Deletes a specific sheet.
List Reports
GET /public/api/apps/{appId}/artifacts/reports
Returns a list of all reports in the specified application with their names and associated query names.
Get Report Details
GET /public/api/apps/{appId}/artifacts/reports/{reportName}
Returns the full specification of a specific report.
Update Report Query
PATCH /public/api/apps/{appId}/artifacts/reports/{reportName}/query
Updates the query associated with a specific report. The request body should be a string containing the name of the new query to associate with the report. The query must exist in the application.
Delete Report
DELETE /public/api/apps/{appId}/artifacts/reports/{reportName}
Deletes a specific report.
Create Artifact
POST /public/api/apps/{appId}/artifacts
Creates a new artifact (query, form, sheet, or report). The request body should be a JSON object with the following properties:
name
The name of the artifact
artifactType
The type of artifact. Must be Query, Form, Sheet, or Report.
specification
The artifact’s specification (base64 encoded string previously retrieved using one of the GET methods above.
Here’s a sample Python script to upload a previously downloaded form artifact:
import requests
import json
import os
# API Configuration
BASE_URL = "https://app.visualdb.com" # If self-hosting replace with your server
APP_ID = "your-app-id"
API_KEY = "your-api-key" # Keep this secret!
# Function to load JSON from a file
def load_json_file(filename):
try:
with open(filename, 'r', encoding='utf-8') as f:
return json.load(f)
except Exception as e:
print(f"Failed to load JSON from {filename}: {e}")
return None
# Prepare the authorization header
def get_auth_header():
return {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Load form data from file
artifact = load_json_file("form.json")
if not artifact:
print("Form data not found")
exit(1)
# Send the request to create the form
endpoint = f"{BASE_URL}/public/api/apps/{APP_ID}/artifacts"
response = requests.post(
endpoint,
headers=get_auth_header(),
json=artifact
)
# Check the response
if response.status_code == 200:
print("Form created successfully!")
else:
print(f"Error creating form: {response.status_code}")
print(f"Response: {response.text}")