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

Required Fields

Field	Type	Description
`resource_type`	string	Must be `"HttpServer"`
`db_id`	string	The database ID (UUIDv4 format) to expose via HTTP. Must match an existing DittoDatabase resource
`listen_addr`	string	Address and port to listen on (format: `"host:port"`).
`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 `db_id`	URL 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

Field	Type	Default	Description
`enable_execute`	boolean	`true`	Enable the `/execute` endpoint for DQL queries
`enable_healthcheck`	boolean	`false`	Enable the health check endpoint

API Endpoints

Execute Endpoint

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

{
  "query": "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 '{
    "query": "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 '{
    "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/my_server/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/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

Configuration

Reference

​Basic Configuration

​Required Fields

​Optional Fields

​Listen Address Configuration

​HTTP API Configuration

​Simple Configuration

​Fine-Grained Configuration

​API Endpoints

​Execute Endpoint

​Health Check Endpoint

​Complete Examples

​Basic HTTP Server

​Custom Base Path

​Multiple HTTP Servers

​Health Check Only Server

​Using the HTTP API

​Query Execution Example

​Health Check Example

​Security Considerations

​Important Notes

​Related Resources