HTTP/REST API Protocol

HTTP/REST API Protocol

HeliosDB provides a comprehensive HTTP/REST API for programmatic access, enabling integration with any language or platform that supports HTTP.

Overview

Property	Value
Protocol	HTTP/1.1, HTTP/2
Port	443 (HTTPS), 8080 (HTTP)
Status	Production
Compatibility	75%+
Auth Methods	API Key, JWT, OAuth 2.0

Quick Start

cURL

# Query with SQL
curl -X POST https://localhost:443/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users LIMIT 10"}'

# Insert data
curl -X POST https://localhost:443/api/v1/tables/users/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

Python (requests)

import requests

base_url = "https://localhost:443/api/v1"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Execute SQL query
response = requests.post(
    f"{base_url}/query",
    headers=headers,
    json={"sql": "SELECT * FROM users WHERE status = 'active'"}
)
result = response.json()
print(result["data"])

JavaScript (fetch)

const baseUrl = 'https://localhost:443/api/v1';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Execute SQL query
const response = await fetch(`${baseUrl}/query`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ sql: 'SELECT * FROM users' })
});
const result = await response.json();
console.log(result.data);

Key Features

• RESTful API design following OpenAPI 3.0 specification
• HTTP/2 support for multiplexed connections
• JSON and MessagePack response formats
• Streaming responses for large result sets
• Rate limiting and throttling
• Comprehensive error handling with detailed messages

API Endpoints

Endpoint	Method	Description
/api/v1/query	POST	Execute SQL query
/api/v1/tables	GET	List all tables
/api/v1/tables/{name}	GET	Get table schema
/api/v1/tables/{name}/rows	GET, POST, PUT, DELETE	CRUD operations
/api/v1/health	GET	Health check
/api/v1/metrics	GET	Prometheus metrics

Documentation

• CONFIGURATION.md - Server configuration options
• COMPATIBILITY.md - API compatibility reference
• EXAMPLES.md - Code examples and patterns

Related Resources

• OpenAPI Specification - Full API spec
• API Reference - Complete API documentation
• Authentication Guide - Auth methods

---

Last Updated: January 2026