HttpServer Resource Configuration

The HttpServer resource creates an HTTP API endpoint for your Ditto database, allowing any HTTP client (including web browsers) to query and manipulate data using standard REST methods. This enables integration with systems that cannot use the Ditto SDK directly.

Basic Configuration

database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode  # Required: use dev_mode for HTTP or provide cert/key for HTTPS
  http_api: true
  enable_healthcheck: true
  serve_docs: true

# Authentication (dev mode - no auth required)
auth: dev_mode

Required Fields

Field	Type	Description
`listen_addr`	string	Address and port to listen on (format: `"host:port"`)
`tls_config`	string or object	TLS configuration. Use `"dev_mode"` for insecure HTTP, or provide `{cert: "path", key: "path"}` for HTTPS
`http_api`	boolean or object	Enable HTTP API endpoints. Use `true` to enable all, `false` to disable all, or an object for fine-grained control

Optional HTTP Server Fields

Request Timeout

Field	Type	Default	Description
`request_timeout_ms`	integer	10000	Timeout for all HTTP requests in milliseconds (min: 0, max: 18446744073709551615)

Health Check Endpoint

Field	Type	Default	Description
`enable_healthcheck`	boolean	`false`	Enable health check endpoint at `GET <listen_addr>/health`. Returns HTTP 200 (OK) status code

API Documentation

Field	Type	Default	Description
`serve_docs`	boolean	`false`	Serve OpenAPI spec at `GET <listen_addr>/docs/edge_server_api.json` and rendered Swagger UI at `GET <listen_addr>/docs/`

TLS Configuration

Configure HTTPS on the HTTP server:

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config:
    cert: "path/to/cert.pem"  # Relative to config file or absolute
    key: "path/to/key.pem"    # Relative to config file or absolute
  http_api: true

Field	Type	Description
`tls_config`	string or object	Required field. Use `"dev_mode"` for insecure HTTP, or provide object with `cert` and `key` for HTTPS
`tls_config.cert`	string	Path to the certificate file. Relative paths are relative to the config file
`tls_config.key`	string	Path to the private key file. Relative paths are relative to the config file

Using tls_config: dev_mode will keep network traffic as HTTP, making it vulnerable to man-in-the-middle attacks. Always use TLS in production by providing certificate and key.

Throttling Configuration

Rate limit requests to prevent DoS attacks:

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true
  throttling:
    strategies:
      - strategy: ip_address
        max_requests: 100
        window_secs: 60
      - strategy: api_key
        max_requests: 50
        window_secs: 60

Field	Type	Default	Description
`throttling`	object/null	`null`	Rate limiting configuration. Set to `null` to disable throttling (not recommended for production)
`throttling.strategies`	array	-	List of throttling strategies to apply. All strategies must be satisfied for a request to proceed (min: 1 strategy)

Throttling Strategy Configuration

Each strategy in the strategies array has the following fields:

Field	Type	Description
`strategy`	string	Strategy type: `"ip_address"`, `"api_key"`, or `"route"`
`max_requests`	integer	Maximum number of requests allowed within the time window (min: 0, max: 4294967295)
`window_secs`	integer	Time window in seconds for the rate limit (min: 0, max: 18446744073709551615)

Strategy Types:

ip_address: Throttle based on client IP address. All requests from the same IP share the same rate limit. Useful for protecting against IP-based DoS attacks
api_key: Throttle based on API key credential provided in the request. Throttling happens BEFORE authentication completes, preventing brute force attacks on specific API keys. Each API key has its own rate limit
route: Throttle based on the request endpoint. All clients share the same rate limit per endpoint. Useful for protecting expensive operations

When multiple strategies are configured, a request must pass ALL rate limit checks. For example, with both IP and API key strategies, the IP address AND the API key must both be under their respective limits.

Listen Address Configuration

The listen_addr field specifies where the HTTP server listens for connections:

IPv4 localhost: "127.0.0.1:PORT" or "localhost:PORT"
IPv6 localhost: "[::1]:PORT" or "[::]:PORT"

Common examples:

listen_addr: "127.0.0.1:8080"    # IPv4 localhost on port 8080
listen_addr: "localhost:3000"     # Localhost on port 3000  
listen_addr: "[::1]:8080"        # IPv6 localhost on port 8080

HTTP API Configuration

The http_api field controls which endpoints are enabled:

Simple Configuration

Enable or disable all endpoints:

http_api: true   # Enable all endpoints
http_api: false  # Disable all endpoints

Fine-Grained Configuration

Control individual endpoints and their limits:

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api:
    execute:
      enabled: true
      max_body_size_mb: 2
    presence: true
    get_logs: true
    attachments_upload:
      enabled: true
      max_body_size_mb: 50  # Larger limit for file uploads
    attachments_download: true

Each endpoint can be configured as:

Boolean: execute: true (uses server defaults)
Object: execute: {enabled: true, max_body_size_mb: 50} (custom limits)

Field	Type	Default	Description
`execute`	boolean or object	`false`	Enable POST `/execute` endpoint for DQL queries
`presence`	boolean or object	`false`	Enable GET `/presence` endpoint
`get_logs`	boolean or object	`false`	Enable GET `/logs` endpoint
`attachments_upload`	boolean or object	`false`	Enable attachment upload endpoints
`attachments_download`	boolean or object	`false`	Enable attachment download endpoints

Endpoint Request Limits Object

When using object form for an endpoint:

Field	Type	Default	Description
`enabled`	boolean	`false`	Whether this endpoint is enabled
`max_header_count`	integer	null	Override max header count for this endpoint
`max_header_size_bytes`	integer	null	Override max header size for this endpoint
`max_request_line_bytes`	integer	null	Override max request line size for this endpoint
`max_body_size_mb`	integer	null	Override max body size for this endpoint (0-65535)

API Endpoints

All endpoints are served directly from the listen address (no base path prefix).

Execute Endpoint

Path: POST /execute Execute DQL queries against the database. Request body:

{
  "query": "SELECT * FROM collection WHERE field = :value",
  "args": {
    "value": "example"
  }
}

Optional headers:

Timeout header: Specify custom timeout for the request

Response:

Success (200): Query results in JSON format
Error (4xx/5xx): Error details with appropriate HTTP status code

Health Check Endpoint

Path: GET /health Simple health check that returns HTTP 200 if the server is running.

Presence Endpoint

Path: GET /presence Get information about connected peers and their presence status.

Logs Endpoint

Path: GET /logs Retrieve logs from the Edge Server and Ditto SDK.

Attachments Endpoints

Upload: Upload new attachments to the database Download: Retrieve attachments from the database

Complete Examples

Basic HTTP Server

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-api-server"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true
  enable_healthcheck: true

auth: dev_mode

Access the API at: http://127.0.0.1:8080/execute

HTTP Server with TLS

database:
  db_id: "87654321-4321-4123-4321-210987654321"
  device_name: "api-gateway"
  auth:
    small_peer_only:
      offline_license_token: "YOUR_LICENSE"

http_server:
  listen_addr: "localhost:3000"
  tls_config:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"
  http_api: true

auth: dev_mode

Access the API at: https://localhost:3000/execute

Health Check Only Server

Minimal configuration for monitoring:

database:
  db_id: "33333333-3333-4333-3333-333333333333"
  device_name: "monitor"
  auth:
    small_peer_only:
      offline_license_token: "MONITOR_LICENSE"

http_server:
  listen_addr: "127.0.0.1:9090"
  tls_config: dev_mode
  http_api: false  # Disable all API endpoints
  enable_healthcheck: true  # Enable health checks only

auth: dev_mode

Access health check at: http://127.0.0.1:9090/health

Advanced Configuration with Fine-Grained Control

database:
  db_id: "44444444-4444-4444-4444-444444444444"
  device_name: "production-server"
  auth:
    server:
      access_token: "TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "customProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"
  request_timeout_ms: 30000  # 30 second timeout
  enable_healthcheck: true
  serve_docs: true
  http_api:
    execute:
      enabled: true
      max_body_size_mb: 10
    presence: true
    get_logs: true
    attachments_upload:
      enabled: true
      max_body_size_mb: 50
    attachments_download: true

auth: dev_mode

Using the HTTP API

Query Execution Example

# Execute a SELECT query
curl -X POST http://127.0.0.1:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE age > :min_age",
    "args": {
      "min_age": 18
    }
  }'

# Insert data
curl -X POST http://127.0.0.1:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "query": "INSERT INTO users DOCUMENTS (:doc)",
    "args": {
      "doc": {
        "id": "user123",
        "name": "John Doe",
        "age": 25
      }
    }
  }'

# Update data
curl -X POST http://127.0.0.1:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "query": "UPDATE users SET age = :new_age WHERE id = :user_id",
    "args": {
      "user_id": "user123",
      "new_age": 26
    }
  }'

Health Check Example

# Check server health
curl -I http://127.0.0.1:8080/health

# Response:
# HTTP/1.1 200 OK

Security Considerations

While Ditto Edge Server is in private preview, no deployments should be considered secure. Use is for development purposes only.

Important Notes

Single Database: Edge Server supports one database per instance
Port Conflicts: Ensure the HTTP server port doesn’t conflict with other services
Restart Required: Changes to HTTP server configuration require Edge Server restart
IPv6 Support: Use bracketed notation for IPv6 addresses (e.g., "[::1]:8080")
TLS Required: The tls_config field is required - use dev_mode for HTTP or provide certificate/key for HTTPS

Ditto Edge Server

Getting Started

Reference

HttpServer Resource Configuration

Basic Configuration

Required Fields

Optional HTTP Server Fields

Request Timeout

Health Check Endpoint

API Documentation

TLS Configuration

Throttling Configuration

Throttling Strategy Configuration

Listen Address Configuration

HTTP API Configuration

Simple Configuration

Fine-Grained Configuration

Endpoint Request Limits Object

API Endpoints

Execute Endpoint

Health Check Endpoint

Presence Endpoint

Logs Endpoint

Attachments Endpoints

Complete Examples

Basic HTTP Server

HTTP Server with TLS

Health Check Only Server

Advanced Configuration with Fine-Grained Control

Using the HTTP API

Query Execution Example

Health Check Example

Security Considerations

Important Notes

​Basic Configuration

​Required Fields

​Optional HTTP Server Fields

​Request Timeout

​Health Check Endpoint

​API Documentation

​TLS Configuration

​Throttling Configuration

​Throttling Strategy Configuration

​Listen Address Configuration

​HTTP API Configuration

​Simple Configuration

​Fine-Grained Configuration

​Endpoint Request Limits Object

​API Endpoints

​Execute Endpoint

​Health Check Endpoint

​Presence Endpoint

​Logs Endpoint

​Attachments Endpoints

​Complete Examples

​Basic HTTP Server

​HTTP Server with TLS

​Health Check Only Server

​Advanced Configuration with Fine-Grained Control

​Using the HTTP API

​Query Execution Example

​Health Check Example

​Security Considerations

​Important Notes

​Related Resources

Basic Configuration

Required Fields

Optional HTTP Server Fields

Request Timeout

Health Check Endpoint

API Documentation

TLS Configuration

Throttling Configuration

Throttling Strategy Configuration

Listen Address Configuration

HTTP API Configuration

Simple Configuration

Fine-Grained Configuration

Endpoint Request Limits Object

API Endpoints

Execute Endpoint

Health Check Endpoint

Presence Endpoint

Logs Endpoint

Attachments Endpoints

Complete Examples

Basic HTTP Server

HTTP Server with TLS

Health Check Only Server

Advanced Configuration with Fine-Grained Control

Using the HTTP API

Query Execution Example

Health Check Example

Security Considerations

Important Notes

Related Resources