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
    db_id: "YOUR_APP_ID"  # Must match a DittoDatabase resource
    listen_addr: "127.0.0.1:8080"
    http_api: true

​
Required Fields

FieldTypeDescription
resource_typestringMust be "HttpServer"
db_idstringThe database ID (UUIDv4 format) to expose via HTTP. Must match an existing DittoDatabase resource
listen_addrstringAddress and port to listen on (format: "host:port").
http_apiboolean/objectEnable HTTP API endpoints. Use true to enable all, false to disable, or an object for fine-grained control

​
Optional Fields

FieldTypeDefaultDescription
base_pathstring/nullUses db_idURL path prefix for the API endpoints. Must be a valid URI path segment

​
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
FieldTypeDefaultDescription
enable_executebooleantrueEnable the /execute endpoint for DQL queries
enable_healthcheckbooleanfalseEnable the health check endpoint

​
API Endpoints

​
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"
  }
}
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.

​
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
    db_id: "12345678-1234-4123-1234-123456789012"
    listen_addr: "127.0.0.1:8080"
    http_api: true
Access the API at: http://127.0.0.1:8080/12345678-1234-4123-1234-123456789012/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
    db_id: "87654321-4321-4123-4321-210987654321"
    base_path: "my_server"  # Custom base path
    listen_addr: "localhost:3000"
    http_api: true
Access the API at: http://localhost:3000/my_server/execute

​
Multiple HTTP Servers

Expose multiple databases on different ports: 
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"
  
  # HTTP server for production
  prod_http:
    resource_type: HttpServer
    db_id: "11111111-1111-4111-1111-111111111111"
    base_path: "prod"
    listen_addr: "127.0.0.1:8080"
    http_api: true
  
  # HTTP server for staging
  staging_http:
    resource_type: HttpServer
    db_id: "22222222-2222-4222-2222-222222222222"
    base_path: "staging"
    listen_addr: "127.0.0.1:8081"
    http_api: true

​
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
    db_id: "33333333-3333-4333-3333-333333333333"
    base_path: "health"
    listen_addr: "127.0.0.1:9090"
    http_api:
      enable_execute: false     # Disable query execution
      enable_healthcheck: true   # Enable health checks only
Access health check at: http://127.0.0.1:9090/health

​
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")