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

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.

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.

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.

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.

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}")