> ## 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.

# HTTP Server

> Expose your Ditto database via REST API endpoints for HTTP client integration

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:

```yaml theme={null}
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](/edge-server/configuration/reference/http-server-resource) 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](/edge-server/configuration/reference/http-server-resource) for complete details on configuring and controlling these endpoints.

## Security Considerations

<Warning>
  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.
</Warning>

### Authentication

Edge Server supports API key authentication to protect your HTTP endpoints. See the [Authentication guide](/edge-server/configuration/authentication) 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.

<Info>
  The spec is generated from the **real HTTP handlers**, not manually maintained documentation. When handler signatures change, the spec automatically reflects those changes.
</Info>

**Access the spec at runtime:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```sh theme={null}
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