REST API: Business Use Case for HeliosDB Nano

Document ID: 15_REST_API.md Version: 1.0 Created: 2025-12-01 Category: Integration & Connectivity HeliosDB Nano Version: 2.5.0+

Executive Summary

HeliosDB Nano’s REST API provides universal HTTP access to all database operations, enabling integration with any language, platform, or low-code tool. With 14 endpoints covering branches, tables, queries, and vector search, organizations can build applications without language-specific drivers, achieving 3x faster integration time and 90% reduction in client-side dependencies. The API supports 10,000+ requests/second with sub-5ms latency for typical operations.

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.

Root Cause Analysis

Factor	Impact	Current Workaround	Limitation
Language-specific drivers	Each client needs compiled bindings	Write FFI wrappers	2-4 weeks per language
Embedded-only access	Cannot query from separate processes	Run proxy server	Adds infrastructure complexity
No low-code integration	Can’t use n8n, Zapier, Retool	Build custom integrations	High maintenance burden

Business Impact Quantification

Metric	Without REST API	With REST API	Improvement
Integration time per client	2-4 weeks	1-2 days	10x faster
Client dependencies	Language bindings required	HTTP client only	90% reduction
Platform compatibility	3-5 languages	Any HTTP client	Universal
DevOps complexity	Binary deployment per language	Single API endpoint	Simplified

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

Why Competitors Cannot Solve This

Technical Barriers

Competitor Category	Limitation	Root Cause	Time to Match
SQLite	No built-in HTTP server	File-based design	6+ months
DuckDB	CLI and library only	Analytics focus	6+ months
Cloud databases	Network required	Architecture	N/A (different model)

Architecture Requirements

To match HeliosDB Nano’s REST API, competitors would need:

Async HTTP Server: Embedded web server with connection pooling
Request Authentication: JWT and API key authentication middleware
Rate Limiting: Per-client request throttling
OpenAPI Specification: Auto-generated documentation

Competitive Moat Analysis

Development Effort to Match:
├── HTTP Server Integration: 4 weeks (Axum/Actix embedding)
├── Authentication Layer: 2 weeks (JWT + API keys)
├── Rate Limiting: 1 week
├── OpenAPI Generation: 2 weeks
└── Total: 9 person-weeks

Why They Won't:
├── SQLite: Maintains "just a library" philosophy
├── DuckDB: Focused on analytics, not serving
└── Others: Different architectural priorities

HeliosDB Nano 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 Nano Core Engine                    │
│              (Query Engine + Storage Layer)                 │
└─────────────────────────────────────────────────────────────┘

Key Capabilities

Capability	Description	Performance
Branch Management	Create, list, delete branches via REST	< 10ms
Table Operations	CRUD for tables and schemas	< 5ms
SQL Queries	Execute SELECT with pagination	< 20ms P99
Statement Execution	INSERT, UPDATE, DELETE, DDL	< 10ms
Vector Search	Similarity search via REST	< 50ms
Data CRUD	JSON-based row operations	< 5ms

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 Nano 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):

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

Results:

Metric	Value
First query latency	< 50ms
Subsequent queries	< 20ms (connection reuse)
Client bundle impact	0 KB (uses fetch API)

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: heliosdb/lite:latest
    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

Results:

Metric	Value
Workflow setup time	15 minutes
Query execution	< 100ms
End-to-end automation	No code required

Example 3: Mobile App - Flutter Integration

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

Dart/Flutter Code:

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();
  }
}

Results:

Metric	Value
App bundle size impact	~50KB (http package)
Query latency (WiFi)	30-50ms
Query latency (4G)	100-200ms
No native bindings required	Yes

Example 4: Serverless Function - AWS Lambda

Scenario: AWS Lambda function processing webhook data

Lambda Handler (Python):

import json
import os
import urllib3

HELIOSDB_URL = os.environ['HELIOSDB_URL']
HELIOSDB_KEY = os.environ['HELIOSDB_API_KEY']

http = urllib3.PoolManager()

def query_heliosdb(sql, params=None):
    """Execute SQL query against HeliosDB REST API."""
    response = http.request(
        'POST',
        f'{HELIOSDB_URL}/v1/branches/main/query',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {HELIOSDB_KEY}'
        },
        body=json.dumps({'sql': sql, 'params': params or []})
    )

    if response.status != 200:
        raise Exception(f'Query failed: {response.data.decode()}')

    return json.loads(response.data.decode())

def execute_heliosdb(sql, params=None):
    """Execute SQL statement against HeliosDB REST API."""
    response = http.request(
        'POST',
        f'{HELIOSDB_URL}/v1/branches/main/execute',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {HELIOSDB_KEY}'
        },
        body=json.dumps({'sql': sql, 'params': params or []})
    )

    if response.status != 200:
        raise Exception(f'Execute failed: {response.data.decode()}')

    return json.loads(response.data.decode())

def lambda_handler(event, context):
    """Process Stripe webhook events."""
    try:
        # Parse webhook payload
        body = json.loads(event['body'])
        event_type = body['type']
        data = body['data']['object']

        if event_type == 'payment_intent.succeeded':
            # Record successful payment
            execute_heliosdb(
                '''INSERT INTO payments (stripe_id, amount, currency, customer_id, created_at)
                   VALUES ($1, $2, $3, $4, NOW())''',
                [data['id'], data['amount'], data['currency'], data['customer']]
            )

            # Update customer lifetime value
            execute_heliosdb(
                '''UPDATE customers
                   SET lifetime_value = lifetime_value + $1
                   WHERE stripe_id = $2''',
                [data['amount'], data['customer']]
            )

        elif event_type == 'customer.created':
            # Create new customer record
            execute_heliosdb(
                '''INSERT INTO customers (stripe_id, email, name, created_at)
                   VALUES ($1, $2, $3, NOW())''',
                [data['id'], data['email'], data.get('name', '')]
            )

        return {
            'statusCode': 200,
            'body': json.dumps({'received': True})
        }

    except Exception as e:
        print(f'Error processing webhook: {e}')
        return {
            'statusCode': 500,
            'body': json.dumps({'error': str(e)})
        }

SAM Template (template.yaml):

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

Results:

Metric	Value
Cold start overhead	+50ms (HTTP client init)
Warm invocation	< 100ms total
No database drivers	Yes (pure HTTP)
Cost per 1M invocations	~$0.20

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 }}
    ]
  }
}

Results:

Metric	Value
Dashboard build time	2 hours
Query response time	< 200ms
No backend code	Yes
Real-time updates	Via refresh button

Market Audience

Primary Segments

Segment 1: Modern Web Development Teams

Attribute	Details
Company Size	10-500 employees
Industry	SaaS, E-commerce, FinTech
Pain Points	Managing multiple database drivers, serverless integration
Decision Makers	Engineering Lead, CTO
Budget Range	$10K-$100K/year for infrastructure
Deployment Model	Microservice/Serverless

Value Proposition: Universal database access from any platform without driver management.

Segment 2: Low-Code/No-Code Builders

Attribute	Details
Company Size	1-50 employees
Industry	All (internal tools, automation)
Pain Points	Unable to integrate embedded databases with workflow tools
Decision Makers	Operations Manager, Business Analyst
Budget Range	$1K-$10K/year
Deployment Model	Cloud-hosted

Value Proposition: Direct database integration with n8n, Zapier, Retool without custom code.

Segment 3: Mobile Development Teams

Attribute	Details
Company Size	5-200 employees
Industry	Consumer apps, B2B mobile
Pain Points	Complex native bindings, offline sync
Decision Makers	Mobile Lead, Head of Engineering
Budget Range	$20K-$200K/year
Deployment Model	Hybrid (API + local cache)

Value Proposition: Simple HTTP-based database access with no native SDK dependencies.

Technical Advantages

Why HeliosDB Nano Excels

Aspect	HeliosDB Nano	Traditional Embedded DBs	Cloud Databases
HTTP Access	Built-in REST API	Not available	Yes
No Driver Required	Yes	No (need bindings)	Yes
Offline Capable	Yes (embedded mode)	Yes	No
Latency	< 5ms (local)	< 1ms	20-100ms
Setup Complexity	Single binary	Per-language setup	Network config

Performance Characteristics

Operation	Throughput	Latency (P99)	Memory
GET /health	50K req/sec	< 1ms	0
POST /query (simple)	10K req/sec	< 20ms	Minimal
POST /query (complex)	5K req/sec	< 100ms	Depends on result size
POST /execute	10K req/sec	< 10ms	Minimal
POST /vector/search	2K req/sec	< 50ms	Depends on index

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

Success Metrics:

Dashboard operational
3+ workflows automated
Team productivity increased

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

Success Metrics:

3+ services using REST API
< 100ms average latency
99.9% uptime

Phase 3: Full Migration (Weeks 7-12)

Target: Replace legacy database proxies

Tactics:

Migrate existing services
Implement caching layer
Document best practices

Success Metrics:

All services migrated
50% reduction in infrastructure
Team can build new integrations in < 1 day

Key Success Metrics

Technical KPIs

Metric	Target	Measurement Method
API latency P99	< 100ms	Application monitoring
Throughput	10K req/sec	Load testing
Error rate	< 0.1%	Error tracking

Business KPIs

Metric	Target	Measurement Method
Integration time	< 2 days	Project tracking
Driver dependencies	0	Dependency audit
Platform coverage	10+	Integration count

Conclusion

HeliosDB Nano’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 Nano’s REST API provides the bridge between embedded database simplicity and universal accessibility.

References

“State of JS 2024” - HTTP clients usage statistics
“Low-Code Platform Market Report” - Gartner 2024
“Serverless Computing Survey” - CNCF 2024
Axum Framework Documentation - Tokio Project

Document Classification: Business Confidential Review Cycle: Quarterly Owner: Product Marketing Adapted for: HeliosDB Nano Embedded Database