Create connection

POST /api/v1/connections

Save database or S3 settings with an encrypted secret.

Access

A Bearer API key for this workspace with write permission is required. The server also checks the owner’s permission for this resource and action. An inaccessible object is not disclosed.

Parameters

Example request parameters or JSON body:

{
  "code": "store-db",
  "name": "Store database",
  "driver": "pgsql",
  "host": "db.example.invalid",
  "port": 5432,
  "database": "catalog",
  "username": "catalog_writer",
  "password": "REPLACE_ME"
}

code, name, driver, host, and database are required. Drivers: pgsql, mysql, mongodb, s3. See driver parameters.

Response 201

The example is shortened; actual responses may include more fields. Sample IDs are placeholders.

{
  "id": 7,
  "code": "store-db",
  "name": "Store database",
  "driver": "pgsql",
  "host": "db.example.invalid",
  "database": "catalog"
}

Send the request

Set BASE to your installation URL without a trailing slash and API_KEY to a secret stored on your server. Client setup and browser JavaScript.

curl

curl --fail-with-body -X POST "$BASE/api/v1/connections" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "code": "store-db",
  "name": "Store database",
  "driver": "pgsql",
  "host": "db.example.invalid",
  "port": 5432,
  "database": "catalog",
  "username": "catalog_writer",
  "password": "REPLACE_ME"
}
JSON

Node.js · server

// Node.js server example. Save as request.mjs.
const response = await fetch(process.env.BASE + "/api/v1/connections", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"code":"store-db","name":"Store database","driver":"pgsql","host":"db.example.invalid","port":5432,"database":"catalog","username":"catalog_writer","password":"REPLACE_ME"}),
  signal: AbortSignal.timeout(120000)
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());

Python

import json
import os
import urllib.request
import urllib.error

body = '{"code":"store-db","name":"Store database","driver":"pgsql","host":"db.example.invalid","port":5432,"database":"catalog","username":"catalog_writer","password":"REPLACE_ME"}'.encode("utf-8")
request = urllib.request.Request(
    os.environ["BASE"] + "/api/v1/connections",
    method="POST",
    headers={"Authorization": "Bearer " + os.environ["API_KEY"],
             "Accept": "application/json", "Content-Type": "application/json"},
    data=body,
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        print(json.load(response))
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode("utf-8", errors="replace"))
    raise

PHP · external client

<?php
$handle = curl_init(getenv("BASE") . "/api/v1/connections");
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("API_KEY"),
        "Accept: application/json",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{"code":"store-db","name":"Store database","driver":"pgsql","host":"db.example.invalid","port":5432,"database":"catalog","username":"catalog_writer","password":"REPLACE_ME"}
JSON,
]);
$content = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
if ($content === false) {
    throw new RuntimeException(curl_error($handle));
}
curl_close($handle);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("HTTP $status: $content");
}
print_r(json_decode($content, true, 512, JSON_THROW_ON_ERROR));

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
    "strings"
)

func main() {
    body := strings.NewReader(`{"code":"store-db","name":"Store database","driver":"pgsql","host":"db.example.invalid","port":5432,"database":"catalog","username":"catalog_writer","password":"REPLACE_ME"}`)
    request, err := http.NewRequest("POST", os.Getenv("BASE") + "/api/v1/connections", body)
    if err != nil { panic(err) }
    request.Header.Set("Authorization", "Bearer " + os.Getenv("API_KEY"))
    request.Header.Set("Accept", "application/json")
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    response, err := client.Do(request)
    if err != nil { panic(err) }
    defer response.Body.Close()
    content, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, content))
    }
    fmt.Println(string(content))
}

If the request fails

401: check the key and its expiry. 403: check permissions, read/write scope, and 2FA. 404: check the ID and workspace. 422: check fields and resource state. 429: respect Retry-After. Errors and retries.