HTTP Server

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

Use unique ports: Each HTTP server must bind to a different port
Limit API access: Only enable the execute endpoint if needed
Monitor health: Use the health check endpoint for monitoring
Secure production: Use TLS and enable authentication for production deployments

Ditto Edge Server

Getting Started

Reference

Basic Configuration

API Endpoints

Security Considerations

Authentication

Network Access

API Documentation

OpenAPI Specification

Interactive Documentation

Using the API

Query Examples

Docker Networking

Best Practices

​Basic Configuration

​API Endpoints

​Security Considerations

​Authentication

​Network Access

​API Documentation

​OpenAPI Specification

​Interactive Documentation

​Using the API

​Query Examples

​Docker Networking

​Best Practices

Basic Configuration

API Endpoints

Security Considerations

Authentication

Network Access

API Documentation

OpenAPI Specification

Interactive Documentation

Using the API

Query Examples

Docker Networking

Best Practices