API examples

Examples assume BASE_URL=https://example.test/postgis-service and a Central acugis_session value. The current service wiring does not support CLI personal access tokens; see Authentication. IDs and names are illustrative.

curl: register and test a connection

export BASE_URL=https://example.test/postgis-service
export ACUGIS_SESSION='central-session-value'

curl --fail-with-body \
  --cookie "acugis_session=$ACUGIS_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"name":"primary","host":"127.0.0.1","port":5432,"sslmode":"disable","admin_username":"postgres","admin_password":"secret"}' \
  "$BASE_URL/api/connections"

curl --fail-with-body \
  --cookie "acugis_session=$ACUGIS_SESSION" \
  -X POST "$BASE_URL/api/connections/1/test"

JavaScript: create and poll a database

Browser requests on the Central site send the cookie with same-origin fetch. This example assumes the service is on that origin.

const base = "/postgis-service";
const created = await fetch(`${base}/api/databases`, {
  method: "POST",
  credentials: "same-origin",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    connection_id: 1,
    name: "spatial_app",
    purpose: "platform",
    enable_postgis: true
  })
}).then(async r => {
  if (!r.ok) throw new Error(await r.text());
  return r.json();
});

let job;
do {
  await new Promise(resolve => setTimeout(resolve, 2000));
  job = await fetch(`${base}/api/jobs/${created.job_id}`, {
    credentials: "same-origin"
  }).then(r => r.json());
} while (job.status === "queued" || job.status === "running");

console.log(job.status, job.result, job.error_message);

Python: upload and queue a GeoPackage import

import os
import requests

base = "https://example.test/postgis-service"
session = requests.Session()
session.cookies.set("acugis_session", os.environ["ACUGIS_SESSION"])

with open("roads.gpkg", "rb") as source:
    upload = session.post(
        f"{base}/api/databases/7/import/upload",
        files={"file": ("roads.gpkg", source, "application/geopackage+sqlite3")},
        timeout=120,
    )
upload.raise_for_status()

queued = session.post(
    f"{base}/api/databases/7/import",
    json={
        "source_path": upload.json()["source_path"],
        "schema": "public",
        "table_name": "roads",
        "srid_policy": "EPSG:4326",
        "overwrite": True,
    },
    timeout=30,
)
queued.raise_for_status()
print(queued.json())

Go: list database tables

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type Table struct {
    Schema       string `json:"schema"`
    Name         string `json:"name"`
    GeometryType string `json:"geometry_type"`
    SRID         int    `json:"srid"`
    RowEstimate  int64  `json:"row_estimate"`
    SizeBytes    int64  `json:"size_bytes"`
    IndexCount   int    `json:"index_count"`
}

func main() {
    req, _ := http.NewRequest(http.MethodGet,
        "https://example.test/postgis-service/api/databases/7/tables?schema=public", nil)
    req.AddCookie(&http.Cookie{Name: "acugis_session", Value: os.Getenv("ACUGIS_SESSION")})
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK { panic(resp.Status) }
    var tables []Table
    if err := json.NewDecoder(resp.Body).Decode(&tables); err != nil { panic(err) }
    fmt.Printf("%+v\n", tables)
}

PHP: queue a backup

<?php
$url = 'https://example.test/postgis-service/api/databases/7/backup';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Cookie: acugis_session=' . getenv('ACUGIS_SESSION'),
    ],
]);
$body = curl_exec($ch);
if ($body === false || curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 202) {
    throw new RuntimeException(curl_error($ch) . ' ' . $body);
}
$job = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
echo "Queued job {$job['job_id']}\n";
curl_close($ch);

WebSocket: log filtering in a browser

const scheme = location.protocol === "https:" ? "wss:" : "ws:";
const ws = new WebSocket(
  `${scheme}//${location.host}/postgis-service/api/terminal/ws/logs?lines=100`
);
ws.binaryType = "arraybuffer";
ws.onopen = () => ws.send(JSON.stringify({ type: "filter", filter: "error" }));
ws.onmessage = event => {
  if (event.data instanceof ArrayBuffer) {
    console.log(new TextDecoder().decode(event.data));
  } else {
    console.log(JSON.parse(event.data));
  }
};