Skip to main content
The HTTP Server resource creates REST API endpoints for your Ditto database, enabling any HTTP client to query and manipulate data without using the Ditto SDK. This is ideal for web applications, third-party integrations, and systems that require standard HTTP access.

​
Basic Configuration

Add an HTTP server to expose your database via REST API: 
resources:
  my_ditto_db:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    auth:
      # ... auth configuration
  
  my_http_server:
    resource_type: HttpServer
    db_id: "YOUR_APP_ID"  # Must match the database ID
    listen_addr: "127.0.0.1:8080"
    http_api: true
See the HTTP server configuration reference for complete details.

​
API Endpoints

The HTTP server provides two main endpoints:
  • Execute endpoint: POST /<base_path>/execute - Execute DQL queries
  • Health check: GET /<base_path> - Simple health status
By default, the base path uses the database ID. You can customize it: 
resources:
  my_http_server:
    resource_type: HttpServer
    db_id: "YOUR_APP_ID"
    base_path: "api"  # Custom base path
    listen_addr: "127.0.0.1:8080"
    http_api: true
See the HTTP server configuration reference for complete details.

​
Security Considerations

Edge Server is currently in preview. It is not recommended for production use.Edge server is under rapid development as a result:
  • APIs may change without notice.
  • Configuration format may change without notice.
  • Features, and behavior may change without notice.
  • This documentation may quickly grow stale or become inaccurate.
If you are experiencing issues, please reach out to your Ditto contact.

​
Authentication

Edge Server supports API key authentication to protect your HTTP endpoints. See the Authentication guide for details on:
  • Generating API keys
  • Configuring identities and permissions
  • Securing your HTTP server

​
Network Access

The HTTP server allows binding to any listen address (e.g., 0.0.0.0 or [::]) to facilitate use inside Docker containers. When exposing the HTTP server to external networks:
  • Always enable authentication in production
  • Use TLS/HTTPS for encrypted connections
  • Consider using a reverse proxy for additional security layers

​
Using the API

​
Query Examples

Execute a SELECT query: 
curl -X POST http://127.0.0.1:8080/api/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/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "query": "INSERT INTO users DOCUMENTS (:doc)",
    "args": {
      "doc": {"id": "user123", "name": "John Doe", "age": 25}
    }
  }'

​
Docker Networking

When using Docker, ensure proper port mapping: 
docker run --rm -p 8080:8080 \
  -v ./config.yaml:/config.yaml \
  edge-server:latest run -c /config.yaml

​
Best Practices

  1. Use unique ports: Each HTTP server must bind to a different port
  2. Limit API access: Only enable the execute endpoint if needed
  3. Monitor health: Use the health check endpoint for monitoring
  4. Secure production: Always use a reverse proxy with authentication for external access
  5. Match database IDs: Ensure the db_id exactly matches your DittoDatabase resource