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