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.
To facilitate use inside docker containers, the HTTP server allows users to bind to ANY listen
address (e.g., 0.0.0.0
or [::]
). There are currently no security restrictions on this feature
nor does the Edge Server implement any authentication or authorization for the HTTP API,
so use caution when exposing the HTTP server to external networks.
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
- 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: Always use a reverse proxy with authentication for external access
- Match database IDs: Ensure the
db_id
exactly matches your DittoDatabase resource