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

resources:
  my_http_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    auth: null  # No authentication (not recommended for production)
    databases:
      my_db_config:  # Key name used as default base_path
        db_id: "YOUR_APP_ID"  # Must match a DittoDatabase resource
        http_api: true

Required Fields

Field	Type	Description
`resource_type`	string	Must be `"HttpServer"`
`listen_addr`	string	Address and port to listen on (format: `"host:port"`)
`auth`	array/null	Set of Identity resource IDs allowed to authenticate to this HTTP server. Set to `null` to disable authentication (not recommended for production). Set to `["identity1", "identity2"]` to require authentication with specific identities
`databases`	object	Database configuration to expose via HTTP. The key is used as the database name, and the value is an `HttpDbConfig` object

Database Configuration (HttpDbConfig)

The databases map entry has the following fields:

Required Fields

Field	Type	Description
`db_id`	string	The database ID (UUIDv4 format) to expose via HTTP. Must match an existing DittoDatabase resource
`http_api`	boolean/object	Enable HTTP API endpoints. Use `true` to enable all, `false` to disable, or an object for fine-grained control

Optional Fields

Field	Type	Default	Description
`base_path`	string/null	Uses the YAML key name	URL path prefix for the API endpoints. Must match pattern `^[A-Za-z0-9_-]+$`
`default_timeout_ms`	integer	5000	Default timeout for HTTP requests in milliseconds. Used when timeout header is 0 or null and `max_timeout_ms` is not null (min: 0, max: 18446744073709551615)
`max_timeout_ms`	integer/null	10000	Maximum timeout allowed for operations in milliseconds. Set to `null` to allow operations to hang forever. To indicate infinite timeout per request, use timeout header of 0 (min: 0, max: 18446744073709551615)

Optional HTTP Server Fields

Health Check Endpoint

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

API Documentation

Field	Type	Default	Description
`serve_docs`	boolean	`true`	Serve OpenAPI spec at `GET <listen_addr>/docs/api.json` and rendered Redoc UI at `GET <listen_addr>/docs/`

TLS Configuration

Configure HTTPS on the HTTP server:

tls_config:
  cert: "path/to/cert.pem"  # Relative to config file or absolute
  key: "path/to/key.pem"    # Relative to config file or absolute

Field	Type	Default	Description
`tls_config`	object/null	`null`	TLS configuration for HTTPS. When provided, the server uses HTTPS on the same port. Leaving this field blank keeps the server as HTTP (not recommended for production)
`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

Leaving tls_config blank will keep network traffic as HTTP, making it vulnerable to man-in-the-middle attacks. Always use TLS in production.

Throttling Configuration

Rate limit requests to prevent DoS attacks:

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:

http_api:
  enable_execute: true           # Enable DQL query execution endpoint (default: false)
  enable_presence: true          # Enable presence endpoint (default: false)
  enable_get_logs: true          # Enable logs endpoint (default: false)
  max_body_size_mb: 2            # Limit request body size (default: 2)
  attachments:
    enable_download: true        # Enable attachment downloads (default: false)
    enable_upload: true          # Enable attachment uploads (default: false)

Field	Type	Default	Description
`enable_execute`	boolean	`false`	Enable the `/execute` endpoint for DQL queries
`enable_presence`	boolean	`false`	Enable the GET presence endpoint
`enable_get_logs`	boolean	`false`	Enable the GET /logs endpoint
`max_body_size_mb`	integer	2	Maximum body size for HTTP requests in MB (0-65535). Increase for large attachment uploads
`attachments`	object	See below	Attachments API configuration

Attachments Configuration

Field	Type	Default	Description
`enable_download`	boolean	`false`	Enable downloading attachments via HTTP
`enable_upload`	boolean	`false`	Enable uploading attachments via HTTP

API Endpoints

All endpoints are prefixed with /<base_path> where base_path defaults to the database key name in the databases configuration.

Execute Endpoint

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

{
  "statement": "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 /<base_path> Simple health check that returns HTTP 200 if the server is running.

Presence Endpoint

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

Logs Endpoint

Path: GET /<base_path>/logs Retrieve logs from the Edge Server.

Attachments Endpoints

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

Complete Examples

Basic HTTP Server

resources:
  # Database configuration
  my_database:
    resource_type: DittoDatabase
    db_id: "12345678-1234-4123-1234-123456789012"
    device_name: "edge-api-server"
    auth:
      server:
        access_token: "YOUR_TOKEN"
        auth_url: "https://your-app.cloud.dittolive.app"
        provider: "__playgroundProvider"

  # HTTP server for the database
  api_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    databases:
      my_api:  # This becomes the default base_path
        db_id: "12345678-1234-4123-1234-123456789012"
        http_api: true

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

Custom Base Path

resources:
  db_config:
    resource_type: DittoDatabase
    db_id: "87654321-4321-4123-4321-210987654321"
    device_name: "api-gateway"
    auth:
      small_peer_only:
        offline_license_token: "YOUR_LICENSE"

  http_config:
    resource_type: HttpServer
    listen_addr: "localhost:3000"
    databases:
      default_name:  # YAML key
        db_id: "87654321-4321-4123-4321-210987654321"
        base_path: "my_server"  # Override with custom base path
        http_api: true

Access the API at: http://localhost:3000/my_server/execute

Health Check Only Server

Minimal configuration for monitoring:

resources:
  monitor_db:
    resource_type: DittoDatabase
    db_id: "33333333-3333-4333-3333-333333333333"
    device_name: "monitor"
    auth:
      small_peer_only:
        offline_license_token: "MONITOR_LICENSE"

  health_server:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:9090"
    databases:
      health:
        db_id: "33333333-3333-4333-3333-333333333333"
        http_api:
          enable_execute: false      # Disable query execution
          enable_healthcheck: true   # Enable health checks only
          enable_presence: false
          enable_get_logs: false

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

Advanced Attachments Configuration with Timeouts

resources:
  my_database:
    resource_type: DittoDatabase
    db_id: "44444444-4444-4444-4444-444444444444"
    device_name: "production-server"
    auth:
      server:
        access_token: "TOKEN"
        auth_url: "https://auth.dittolive.app"
        provider: "customProvider"

  advanced_http:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    databases:
      api:
        db_id: "44444444-4444-4444-4444-444444444444"
        default_timeout_ms: 3000      # 3 second default timeout
        max_timeout_ms: 30000          # 30 second max timeout
        http_api:
          enable_execute: true
          enable_healthcheck: true
          enable_presence: true
          enable_get_logs: true
          max_body_size_mb: 10         # Allow 10MB uploads
          attachments:
            enable_download: true
            enable_upload: true

Using the HTTP API

Query Execution Example

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

# Insert data
curl -X POST http://127.0.0.1:8080/my_server/execute \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "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/my_server/execute \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "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/my_server

# 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

Database ID Matching: The db_id must exactly match a DittoDatabase resource in your configuration
Port Conflicts: Ensure each HttpServer uses a unique port to avoid binding conflicts
Restart Required: Changes to HTTP server configuration require Edge Server restart
IPv6 Support: Use bracketed notation for IPv6 addresses (e.g., "[::1]:8080")

Getting Started

Key Concepts

Demo Apps

Additional Resources

HttpServer Resource Configuration

Basic Configuration

Required Fields

Database Configuration (HttpDbConfig)

Required Fields

Optional Fields

Optional HTTP Server Fields

Health Check Endpoint

API Documentation

TLS Configuration

Throttling Configuration

Throttling Strategy Configuration

Listen Address Configuration

HTTP API Configuration

Simple Configuration

Fine-Grained Configuration

Attachments Configuration

API Endpoints

Execute Endpoint

Health Check Endpoint

Presence Endpoint

Logs Endpoint

Attachments Endpoints

Complete Examples

Basic HTTP Server

Custom Base Path

Health Check Only Server

Advanced Attachments Configuration with Timeouts

Using the HTTP API

Query Execution Example

Health Check Example

Security Considerations

Important Notes

Getting Started

Key Concepts

Demo Apps

Additional Resources

​Basic Configuration

​Required Fields

​Database Configuration (HttpDbConfig)

​Required Fields

​Optional Fields

​Optional HTTP Server Fields

​Health Check Endpoint

​API Documentation

​TLS Configuration

​Throttling Configuration

​Throttling Strategy Configuration

​Listen Address Configuration

​HTTP API Configuration

​Simple Configuration

​Fine-Grained Configuration

​Attachments Configuration

​API Endpoints

​Execute Endpoint

​Health Check Endpoint

​Presence Endpoint

​Logs Endpoint

​Attachments Endpoints

​Complete Examples

​Basic HTTP Server

​Custom Base Path

​Health Check Only Server

​Advanced Attachments Configuration with Timeouts

​Using the HTTP API

​Query Execution Example

​Health Check Example

​Security Considerations

​Important Notes

​Related Resources

Basic Configuration

Required Fields

Database Configuration (HttpDbConfig)

Required Fields

Optional Fields

Optional HTTP Server Fields

Health Check Endpoint

API Documentation

TLS Configuration

Throttling Configuration

Throttling Strategy Configuration

Listen Address Configuration

HTTP API Configuration

Simple Configuration

Fine-Grained Configuration

Attachments Configuration

API Endpoints

Execute Endpoint

Health Check Endpoint

Presence Endpoint

Logs Endpoint

Attachments Endpoints

Complete Examples

Basic HTTP Server

Custom Base Path

Health Check Only Server

Advanced Attachments Configuration with Timeouts

Using the HTTP API

Query Execution Example

Health Check Example

Security Considerations

Important Notes

Related Resources