HTTP/REST API Configuration

Complete configuration reference for HTTP/REST API in HeliosDB.

Server Configuration

Basic Settings

[http]
# Enable HTTP API
enabled = true

# HTTP port (plain HTTP, typically for development)
http_port = 8080

# HTTPS port (TLS, for production)
https_port = 443

# Bind address
bind_address = "0.0.0.0"

# Enable HTTP/2
http2_enabled = true

# Request body size limit (bytes)
max_body_size = 104857600  # 100MB

# Request timeout (seconds)
request_timeout = 300

TLS/SSL Configuration

[http.tls]
# Enable TLS
enabled = true

# Certificate file path
cert_file = "/path/to/server.crt"

# Private key file path
key_file = "/path/to/server.key"

# CA certificate for client verification (optional)
ca_file = "/path/to/ca.crt"

# Require client certificates
client_auth_required = false

# Minimum TLS version
min_version = "1.2"

# Cipher suites (optional, defaults to secure set)
cipher_suites = [
    "TLS_AES_256_GCM_SHA384",
    "TLS_CHACHA20_POLY1305_SHA256"
]

Authentication

[http.auth]
# Authentication methods: api_key, jwt, oauth2, basic
methods = ["api_key", "jwt"]

# API key settings
[http.auth.api_key]
header_name = "Authorization"
prefix = "Bearer"

# JWT settings
[http.auth.jwt]
secret = "your-jwt-secret"
issuer = "heliosdb"
audience = "heliosdb-api"
expiration = 3600  # 1 hour

# OAuth 2.0 settings
[http.auth.oauth2]
provider = "custom"
authorization_url = "https://auth.example.com/authorize"
token_url = "https://auth.example.com/token"
client_id = "your-client-id"

Rate Limiting

[http.rate_limit]
# Enable rate limiting
enabled = true

# Requests per minute (per API key)
requests_per_minute = 1000

# Requests per hour (per API key)
requests_per_hour = 10000

# Burst allowance
burst_size = 100

# Rate limit by IP (for anonymous requests)
anonymous_requests_per_minute = 60

CORS Configuration

[http.cors]
# Enable CORS
enabled = true

# Allowed origins (* for all)
allowed_origins = ["https://app.example.com"]

# Allowed methods
allowed_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]

# Allowed headers
allowed_headers = ["Authorization", "Content-Type", "X-Request-ID"]

# Exposed headers
exposed_headers = ["X-Request-ID", "X-RateLimit-Remaining"]

# Allow credentials
allow_credentials = true

# Max age for preflight cache (seconds)
max_age = 86400

Response Configuration

[http.response]
# Default response format: json, msgpack
default_format = "json"

# Pretty print JSON responses
pretty_json = false

# Include query execution time in response
include_timing = true

# Include request ID in response
include_request_id = true

# Compression threshold (bytes, 0 to disable)
compression_threshold = 1024

# Supported compression: gzip, br (brotli), zstd
compression_algorithms = ["gzip", "br"]

Streaming Configuration

[http.streaming]
# Enable streaming responses
enabled = true

# Chunk size for streaming (rows)
chunk_size = 1000

# Stream timeout (seconds)
stream_timeout = 3600

# Enable Server-Sent Events
sse_enabled = true

# Enable WebSocket
websocket_enabled = true

Environment Variables

Variable	Description	Default
HELIOSDB_HTTP_ENABLED	Enable HTTP API	true
HELIOSDB_HTTP_PORT	HTTP port	8080
HELIOSDB_HTTPS_PORT	HTTPS port	443
HELIOSDB_HTTP_TLS_ENABLED	Enable TLS	false
HELIOSDB_HTTP_TLS_CERT	TLS certificate path	-
HELIOSDB_HTTP_TLS_KEY	TLS key path	-
HELIOSDB_HTTP_AUTH_SECRET	JWT secret	-
HELIOSDB_HTTP_RATE_LIMIT	Requests per minute	1000

Request Headers

Header	Description	Required
Authorization	Authentication token	Yes
Content-Type	Request content type	For POST/PUT
Accept	Response format (application/json, application/msgpack)	No
Accept-Encoding	Compression (gzip, br)	No
X-Request-ID	Request tracking ID	No
X-Tenant-ID	Multi-tenant identifier	For multi-tenant

Response Headers

Header	Description
X-Request-ID	Request tracking ID
X-Response-Time	Query execution time (ms)
X-RateLimit-Limit	Rate limit maximum
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Rate limit reset time

---

Last Updated: January 2026