Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ditto.live/llms.txt

Use this file to discover all available pages before exploring further.

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: 
database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://YOUR-AUTH-URL"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode  # Set to dev_mode for insecure HTTP, or provide cert/key for TLS
  http_api: true
  enable_healthcheck: true
  serve_docs: true

# HTTP API authentication (dev mode - no auth)
auth: dev_mode
See the HTTP server configuration reference for complete details.

​
API Endpoints

The HTTP server provides the following endpoints:
  • Execute endpoint: POST /<base_path>/execute - Execute DQL queries
  • Attachments: POST /<base_path>/attachments/upload and GET /<base_path>/attachments/{id} - Upload and download attachments
  • Presence: GET /<base_path>/presence - View the presence graph of connected peers
  • Logs: GET /<base_path>/logs - Download server logs as a .tar.gz file
  • API documentation: GET /<base_path>/docs - Access OpenAPI specification and Swagger UI
  • Health check: GET /<base_path>/health - Simple health status
For example, with the config above:
  • Execute endpoint: POST http://127.0.0.1:8080/execute
  • Health check: GET http://127.0.0.1:8080/health
  • API docs: GET http://127.0.0.1:8080/docs
See the HTTP server configuration reference for complete details on configuring and controlling these endpoints.

​
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

​
API Documentation

​
OpenAPI Specification

The Edge Server automatically generates a comprehensive OpenAPI 3.1 specification from your configuration file. The spec is generated directly from the actual HTTP handlers used at runtime, ensuring it always stays in sync with the server’s behavior—even as handlers are updated.
The spec is generated from the real HTTP handlers, not manually maintained documentation. When handler signatures change, the spec automatically reflects those changes.
Access the spec at runtime: 
# View the OpenAPI spec while server is running
curl http://127.0.0.1:8080/docs/edge_server_api.json | jq .

# Check what endpoints are available
curl http://127.0.0.1:8080/docs/edge_server_api.json | jq '.paths | keys'

# View a specific endpoint's schema
curl http://127.0.0.1:8080/docs/edge_server_api.json | jq '.paths["/execute"]'
Generate offline without starting the server: 
# Generate spec from config file (fast: <100ms)
ditto-edge-server config open-api --config config.yaml

# Save to file for use with external tools
ditto-edge-server config open-api --config config.yaml --output openapi.json
Development workflow examples: 
# Generate TypeScript SDK for your frontend
ditto-edge-server config open-api --config config.yaml --output spec.json
openapi-generator-cli generate -i spec.json -g typescript-axios -o ./sdk

# Validate your config produces a valid OpenAPI spec
ditto-edge-server config open-api --config config.yaml | \
  npx @openapitools/openapi-generator-cli validate -i /dev/stdin

# Generate Postman collection
ditto-edge-server config open-api --config config.yaml | \
  docker run --rm -i -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /dev/stdin -g postman-collection -o /local/postman
Use cases:
  • Interactive docs - Swagger UI, ReDoc, Stoplight
  • Client generation - Type-safe SDKs in 50+ languages (TypeScript, Python, Go, Rust, Java, etc.)
  • API testing - Postman collections, Insomnia workspaces
  • Contract testing - Pact, Dredd, Schemathesis
  • Documentation - Static site generation, developer portals
  • Validation - CI/CD spec validation, breaking change detection

​
Interactive Documentation

Access the built-in Swagger UI documentation while the server is running: 
# Open in browser
open http://127.0.0.1:8080/docs
This provides an interactive interface to:
  • Browse all available endpoints
  • View request/response schemas
  • Try out API calls directly from the browser
  • See authentication requirements
  • Explore error responses
The Swagger UI automatically reflects your configuration—only enabled endpoints appear.

​
Using the API

​
Query Examples

Execute a SELECT query: 
curl -X POST http://127.0.0.1:8080/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/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: Use TLS and enable authentication for production deployments