REST API

Executive Summary

HeliosDB Lite's REST API provides universal HTTP access to all database operations, enabling integration with any language, platform, or low-code tool.

---

Problem Being Solved

Core Problem Statement

Traditional embedded databases require language-specific drivers and compiled bindings, making integration with diverse systems (mobile apps, serverless functions, low-code platforms, IoT devices) complex and costly. Organizations need universal HTTP-based access that works with any client capable of making HTTP requests.

Who Suffers Most

• Full-Stack Developers: Need to access database from frontend (React, Vue) without backend proxy
• DevOps Engineers: Managing multiple language runtimes for database access
• Low-Code/No-Code Users: Unable to integrate embedded database with workflow tools
• Mobile Developers: Complex native binding requirements for iOS/Android

---

HeliosDB Lite Solution

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    HTTP Clients                              │
│  (curl, Postman, React, Python, Go, n8n, Zapier, etc.)     │
├─────────────────────────────────────────────────────────────┤
│                    REST API Layer                            │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│  │   Branches  │   Tables    │   Query     │   Vector    │ │
│  │   CRUD      │   CRUD      │   Execute   │   Search    │ │
│  └─────────────┴─────────────┴─────────────┴─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┬────────────────────────────────────┐  │
│  │  Auth Middleware │  Rate Limiting                     │  │
│  │  (JWT/API Key)   │  (Per-client throttle)            │  │
│  └─────────────────┴────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                HeliosDB-Lite Core Engine                    │
│              (Query Engine + Storage Layer)                 │
└─────────────────────────────────────────────────────────────┘

---

Concrete Examples with Code, Config & Architecture

Example 1: Frontend Application - Direct Database Access

Scenario: React application needs to query database without backend proxy

Architecture:

React Frontend (Browser)
    ↓ HTTP/REST
HeliosDB-Lite REST API (:8080)
    ↓
In-Process Database

Configuration (heliosdb.toml):

[server]
host = "0.0.0.0"
port = 8080

[api]
enabled = true
base_path = "/v1"
cors_origins = ["http://localhost:3000", "https://myapp.com"]

[auth]
method = "api_key"
api_keys = ["sk_live_abc123", "sk_test_xyz789"]

[rate_limit]
requests_per_minute = 1000
burst_size = 100

Frontend Code (React/TypeScript):

// src/lib/heliosdb.ts
const API_BASE = 'http://localhost:8080/v1';
const API_KEY = process.env.REACT_APP_HELIOSDB_KEY;

interface QueryResponse<T> {
  columns: string[];
  rows: T[];
  row_count: number;
  execution_time_ms: number;
}

export async function query<T>(sql: string, params?: any[]): Promise<T[]> {
  const response = await fetch(`${API_BASE}/branches/main/query`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ sql, params })
  });

  if (!response.ok) {
    throw new Error(`Query failed: ${response.statusText}`);
  }

  const data: QueryResponse<T> = await response.json();
  return data.rows;
}

// Usage in React component
import { useQuery } from '@tanstack/react-query';

interface User {
  id: number;
  name: string;
  email: string;
}

function UserList() {
  const { data: users, isLoading } = useQuery({
    queryKey: ['users'],
    queryFn: () => query<User>('SELECT id, name, email FROM users WHERE active = $1', [true])
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name} - {user.email}</li>
      ))}
    </ul>
  );
}

---

Example 2: Low-Code Integration - n8n Workflow

Scenario: Automated workflow querying database and posting to Slack

n8n Workflow Configuration:

{
  "nodes": [
    {
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger",
      "parameters": {
        "rule": { "interval": [{ "field": "hours", "hour": 9 }] }
      }
    },
    {
      "name": "Query HeliosDB",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "method": "POST",
        "url": "http://heliosdb:8080/v1/branches/main/query",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "Content-Type", "value": "application/json" }
          ]
        },
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            {
              "name": "sql",
              "value": "SELECT COUNT(*) as count, status FROM orders WHERE created_at > NOW() - INTERVAL '24 hours' GROUP BY status"
            }
          ]
        }
      }
    },
    {
      "name": "Format Message",
      "type": "n8n-nodes-base.set",
      "parameters": {
        "values": {
          "string": [
            {
              "name": "message",
              "value": "Daily Orders Report:\n{{ $json.rows.map(r => `${r.status}: ${r.count}`).join('\\n') }}"
            }
          ]
        }
      }
    },
    {
      "name": "Post to Slack",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#sales-reports",
        "text": "={{ $json.message }}"
      }
    }
  ]
}

Docker Compose for n8n + HeliosDB:

version: '3.8'
services:
  heliosdb:
    image: registry.example.com/heliosdb-lite:latest  # licensed image from HeliosDB sales, or built from the Lite Dockerfile
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      - HELIOSDB_API_KEY=sk_n8n_workflow_key

  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=password
    volumes:
      - ./n8n_data:/home/node/.n8n
    depends_on:
      - heliosdb

---

Example 3: Mobile App - Flutter Integration

Scenario: Flutter mobile app with offline-first sync to HeliosDB REST API

Dart/Flutter Code:

// lib/services/heliosdb_service.dart
import 'dart:convert';
import 'package:http/http.dart' as http;

class HeliosDBService {
  final String baseUrl;
  final String apiKey;

  HeliosDBService({required this.baseUrl, required this.apiKey});

  Future<List<Map<String, dynamic>>> query(String sql, [List<dynamic>? params]) async {
    final response = await http.post(
      Uri.parse('$baseUrl/v1/branches/main/query'),
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer $apiKey',
      },
      body: jsonEncode({
        'sql': sql,
        'params': params ?? [],
      }),
    );

    if (response.statusCode != 200) {
      throw Exception('Query failed: ${response.body}');
    }

    final data = jsonDecode(response.body);
    return List<Map<String, dynamic>>.from(data['rows']);
  }

  Future<int> execute(String sql, [List<dynamic>? params]) async {
    final response = await http.post(
      Uri.parse('$baseUrl/v1/branches/main/execute'),
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer $apiKey',
      },
      body: jsonEncode({
        'sql': sql,
        'params': params ?? [],
      }),
    );

    if (response.statusCode != 200) {
      throw Exception('Execute failed: ${response.body}');
    }

    final data = jsonDecode(response.body);
    return data['affected_rows'];
  }

  Future<List<Map<String, dynamic>>> vectorSearch(
    String table,
    List<double> queryVector,
    {int limit = 10}
  ) async {
    final response = await http.post(
      Uri.parse('$baseUrl/v1/branches/main/vector/search'),
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer $apiKey',
      },
      body: jsonEncode({
        'table': table,
        'query_vector': queryVector,
        'limit': limit,
      }),
    );

    if (response.statusCode != 200) {
      throw Exception('Vector search failed: ${response.body}');
    }

    final data = jsonDecode(response.body);
    return List<Map<String, dynamic>>.from(data['results']);
  }
}

// Usage in Flutter app
class ProductRepository {
  final HeliosDBService _db;

  ProductRepository(this._db);

  Future<List<Product>> getProducts() async {
    final rows = await _db.query(
      'SELECT id, name, price, image_url FROM products WHERE active = \$1',
      [true],
    );
    return rows.map((r) => Product.fromJson(r)).toList();
  }

  Future<List<Product>> findSimilarProducts(List<double> embedding) async {
    final results = await _db.vectorSearch('products', embedding, limit: 5);
    return results.map((r) => Product.fromJson(r)).toList();
  }
}

---

Example 4: Serverless Function - AWS Lambda

Scenario: AWS Lambda function processing webhook data

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Parameters:
  HeliosDBUrl:
    Type: String
  HeliosDBApiKey:
    Type: String
    NoEcho: true

Resources:
  WebhookFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: app.lambda_handler
      Runtime: python3.11
      Timeout: 30
      MemorySize: 256
      Environment:
        Variables:
          HELIOSDB_URL: !Ref HeliosDBUrl
          HELIOSDB_API_KEY: !Ref HeliosDBApiKey
      Events:
        Webhook:
          Type: Api
          Properties:
            Path: /webhook
            Method: post

---

Example 5: Retool Admin Dashboard

Scenario: Internal admin dashboard for customer support

Retool Resource Configuration:

{
  "name": "HeliosDB Production",
  "type": "REST API",
  "baseUrl": "https://db.mycompany.com/v1",
  "authentication": {
    "type": "bearer",
    "token": "{{ HELIOSDB_API_KEY }}"
  },
  "defaultHeaders": {
    "Content-Type": "application/json"
  }
}

Retool Query - Customer Search:

// Query: searchCustomers
{
  "resource": "HeliosDB Production",
  "method": "POST",
  "path": "/branches/main/query",
  "body": {
    "sql": `
      SELECT
        c.id, c.name, c.email, c.created_at,
        COUNT(o.id) as order_count,
        SUM(o.total) as lifetime_value
      FROM customers c
      LEFT JOIN orders o ON c.id = o.customer_id
      WHERE c.email ILIKE $1 OR c.name ILIKE $1
      GROUP BY c.id
      ORDER BY c.created_at DESC
      LIMIT 50
    `,
    "params": ["%" + {{ searchInput.value }} + "%"]
  }
}

Retool Query - Update Customer:

// Query: updateCustomer
{
  "resource": "HeliosDB Production",
  "method": "POST",
  "path": "/branches/main/execute",
  "body": {
    "sql": `
      UPDATE customers
      SET
        name = $1,
        email = $2,
        notes = $3,
        updated_at = NOW()
      WHERE id = $4
    `,
    "params": [
      {{ nameInput.value }},
      {{ emailInput.value }},
      {{ notesInput.value }},
      {{ customersTable.selectedRow.id }}
    ]
  }
}

---

Adoption Strategy

Phase 1: Internal Tools (Weeks 1-2)

Target: Admin dashboards and internal workflows

Tactics:

• Set up Retool/n8n integration
• Create customer support dashboard
• Automate daily reports

Phase 2: API-First Applications (Weeks 3-6)

Target: New microservices and mobile apps

Tactics:

• Integrate with serverless functions
• Build mobile app backend
• Set up monitoring

Phase 3: Full Migration (Weeks 7-12)

Target: Replace legacy database proxies

Tactics:

• Migrate existing services
• Implement caching layer
• Document best practices

---

Conclusion

HeliosDB Lite's REST API transforms an embedded database into a universally accessible data platform. By providing HTTP-based access to all database operations, organizations can integrate with any client - from React frontends to n8n workflows to Flutter mobile apps - without managing language-specific drivers or complex deployment configurations.

The key differentiators are:

• Universal Access: Any HTTP client can query the database
• Zero Driver Dependencies: No native bindings or FFI required
• Full Feature Parity: REST API exposes all database capabilities including vector search
• Embedded Simplicity: Single binary deployment with no external dependencies

For organizations building modern, polyglot applications, HeliosDB Lite's REST API provides the bridge between embedded database simplicity and universal accessibility.