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"
    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"`)
`databases`	object	Map of database configurations to expose via HTTP. Each key is the database name, and the value is an `HttpDbConfig` object

Database Configuration (HttpDbConfig)

Each entry in the databases map 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)

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
  enable_healthcheck: false      # Disable health check endpoint
  enable_presence: true          # Enable presence endpoint
  enable_get_logs: true          # Enable logs endpoint
  max_body_size_mb: 2            # Limit request body size
  attachments:
    enable_download: true
    enable_upload: true

Field	Type	Default	Description
`enable_execute`	boolean	`true`	Enable the `/execute` endpoint for DQL queries
`enable_healthcheck`	boolean	`false`	Enable the health check endpoint
`enable_presence`	boolean	`true`	Enable the GET presence endpoint
`enable_get_logs`	boolean	`true`	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	`true`	Enable downloading attachments via HTTP
`enable_upload`	boolean	`true`	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

Multiple Databases on One HTTP Server

Expose multiple databases on a single HTTP server with different base paths:

resources:
  # First database
  prod_db:
    resource_type: DittoDatabase
    db_id: "11111111-1111-4111-1111-111111111111"
    device_name: "prod-server"
    auth:
      server:
        access_token: "PROD_TOKEN"
        auth_url: "https://prod.dittolive.app"
        provider: "productionProvider"

  # Second database
  staging_db:
    resource_type: DittoDatabase
    db_id: "22222222-2222-4222-2222-222222222222"
    device_name: "staging-server"
    auth:
      server:
        access_token: "STAGING_TOKEN"
        auth_url: "https://staging.dittolive.app"
        provider: "stagingProvider"

  # Single HTTP server exposing both databases
  multi_db_http:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    databases:
      prod:  # Accessible at /prod/*
        db_id: "11111111-1111-4111-1111-111111111111"
        http_api: true
      staging:  # Accessible at /staging/*
        db_id: "22222222-2222-4222-2222-222222222222"
        http_api: true

Access the APIs at:

Production: http://127.0.0.1:8080/prod/execute
Staging: http://127.0.0.1:8080/staging/execute

Multiple HTTP Servers

Expose databases on different ports:

resources:
  prod_db:
    resource_type: DittoDatabase
    db_id: "11111111-1111-4111-1111-111111111111"
    device_name: "prod-server"
    auth:
      server:
        access_token: "PROD_TOKEN"
        auth_url: "https://prod.dittolive.app"
        provider: "productionProvider"

  staging_db:
    resource_type: DittoDatabase
    db_id: "22222222-2222-4222-2222-222222222222"
    device_name: "staging-server"
    auth:
      server:
        access_token: "STAGING_TOKEN"
        auth_url: "https://staging.dittolive.app"
        provider: "stagingProvider"

  # HTTP server for production on port 8080
  prod_http:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8080"
    databases:
      api:
        db_id: "11111111-1111-4111-1111-111111111111"
        http_api: true

  # HTTP server for staging on port 8081
  staging_http:
    resource_type: HttpServer
    listen_addr: "127.0.0.1:8081"
    databases:
      api:
        db_id: "22222222-2222-4222-2222-222222222222"
        http_api: true

Access the APIs at:

Production: http://127.0.0.1:8080/api/execute
Staging: http://127.0.0.1:8081/api/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")

Ditto Edge Server

Getting Started

Reference

HttpServer Resource Configuration

Basic Configuration

Required Fields

Database Configuration (HttpDbConfig)

Required Fields

Optional Fields

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

Multiple Databases on One HTTP Server

Multiple HTTP Servers

Health Check Only Server

Advanced Attachments Configuration with Timeouts

Using the HTTP API

Query Execution Example

Health Check Example

Security Considerations

Important Notes

Ditto Edge Server

Getting Started

Reference

​Basic Configuration

​Required Fields

​Database Configuration (HttpDbConfig)

​Required Fields

​Optional Fields

​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

​Multiple Databases on One HTTP Server

​Multiple HTTP Servers

​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

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

Multiple Databases on One HTTP Server

Multiple HTTP Servers

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