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

# HttpServer Resource Configuration

> Configure an HTTP API server to expose your Ditto database via REST endpoints

The `HttpServer` resource creates an HTTP API endpoint for your Ditto database, allowing any HTTP client (including web browsers) to query and manipulate data using standard REST methods. This enables integration with systems that cannot use the Ditto SDK directly.

## Basic Configuration

```yaml theme={null}
database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode  # Required: use dev_mode for HTTP or provide cert/key for HTTPS
  http_api: true
  enable_healthcheck: true
  serve_docs: true

# Authentication (dev mode - no auth required)
auth: dev_mode
```

## Required Fields

| Field         | Type              | Description                                                                                                        |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `listen_addr` | string            | Address and port to listen on (format: `"host:port"`)                                                              |
| `tls_config`  | string or object  | TLS configuration. Use `"dev_mode"` for insecure HTTP, or provide `{cert: "path", key: "path"}` for HTTPS          |
| `http_api`    | boolean or object | Enable HTTP API endpoints. Use `true` to enable all, `false` to disable all, or an object for fine-grained control |

## Optional HTTP Server Fields

### Request Timeout

| Field                | Type    | Default | Description                                                                       |
| -------------------- | ------- | ------- | --------------------------------------------------------------------------------- |
| `request_timeout_ms` | integer | 10000   | Timeout for all HTTP requests in milliseconds (min: 0, max: 18446744073709551615) |

### Health Check Endpoint

| Field                | Type    | Default | Description                                                                                   |
| -------------------- | ------- | ------- | --------------------------------------------------------------------------------------------- |
| `enable_healthcheck` | boolean | `false` | Enable health check endpoint at `GET <listen_addr>/health`. Returns HTTP 200 (OK) status code |

### API Documentation

| Field        | Type    | Default | Description                                                                                                              |
| ------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `serve_docs` | boolean | `false` | Serve OpenAPI spec at `GET <listen_addr>/docs/edge_server_api.json` and rendered Swagger UI at `GET <listen_addr>/docs/` |

### TLS Configuration

Configure HTTPS on the HTTP server:

```yaml theme={null}
http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config:
    cert: "path/to/cert.pem"  # Relative to config file or absolute
    key: "path/to/key.pem"    # Relative to config file or absolute
  http_api: true
```

| Field             | Type             | Description                                                                                           |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `tls_config`      | string or object | Required field. Use `"dev_mode"` for insecure HTTP, or provide object with `cert` and `key` for HTTPS |
| `tls_config.cert` | string           | Path to the certificate file. Relative paths are relative to the config file                          |
| `tls_config.key`  | string           | Path to the private key file. Relative paths are relative to the config file                          |

<Warning>
  Using `tls_config: dev_mode` will keep network traffic as HTTP, making it vulnerable to man-in-the-middle attacks. Always use TLS in production by providing certificate and key.
</Warning>

### Throttling Configuration

Rate limit requests to prevent DoS attacks:

```yaml theme={null}
http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true
  throttling:
    strategies:
      - strategy: ip_address
        max_requests: 100
        window_secs: 60
      - strategy: api_key
        max_requests: 50
        window_secs: 60
```

| Field                   | Type        | Default | Description                                                                                                         |
| ----------------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `throttling`            | object/null | `null`  | Rate limiting configuration. Set to `null` to disable throttling (not recommended for production)                   |
| `throttling.strategies` | array       | -       | List of throttling strategies to apply. All strategies must be satisfied for a request to proceed (min: 1 strategy) |

#### Throttling Strategy Configuration

Each strategy in the `strategies` array has the following fields:

| Field          | Type    | Description                                                                         |
| -------------- | ------- | ----------------------------------------------------------------------------------- |
| `strategy`     | string  | Strategy type: `"ip_address"`, `"api_key"`, or `"route"`                            |
| `max_requests` | integer | Maximum number of requests allowed within the time window (min: 0, max: 4294967295) |
| `window_secs`  | integer | Time window in seconds for the rate limit (min: 0, max: 18446744073709551615)       |

**Strategy Types:**

* **`ip_address`**: Throttle based on client IP address. All requests from the same IP share the same rate limit. Useful for protecting against IP-based DoS attacks
* **`api_key`**: Throttle based on API key credential provided in the request. Throttling happens BEFORE authentication completes, preventing brute force attacks on specific API keys. Each API key has its own rate limit
* **`route`**: Throttle based on the request endpoint. All clients share the same rate limit per endpoint. Useful for protecting expensive operations

<Info>
  When multiple strategies are configured, a request must pass ALL rate limit checks. For example, with both IP and API key strategies, the IP address AND the API key must both be under their respective limits.
</Info>

## Listen Address Configuration

The `listen_addr` field specifies where the HTTP server listens for connections:

* **IPv4 localhost**: `"127.0.0.1:PORT"` or `"localhost:PORT"`
* **IPv6 localhost**: `"[::1]:PORT"` or `"[::]:PORT"`

Common examples:

```yaml theme={null}
listen_addr: "127.0.0.1:8080"    # IPv4 localhost on port 8080
listen_addr: "localhost:3000"     # Localhost on port 3000  
listen_addr: "[::1]:8080"        # IPv6 localhost on port 8080
```

## HTTP API Configuration

The `http_api` field controls which endpoints are enabled:

### Simple Configuration

Enable or disable all endpoints:

```yaml theme={null}
http_api: true   # Enable all endpoints
http_api: false  # Disable all endpoints
```

### Fine-Grained Configuration

Control individual endpoints and their limits:

```yaml theme={null}
http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api:
    execute:
      enabled: true
      max_body_size_mb: 2
    presence: true
    get_logs: true
    attachments_upload:
      enabled: true
      max_body_size_mb: 50  # Larger limit for file uploads
    attachments_download: true
```

Each endpoint can be configured as:

* **Boolean**: `execute: true` (uses server defaults)
* **Object**: `execute: {enabled: true, max_body_size_mb: 50}` (custom limits)

| Field                  | Type              | Default | Description                                     |
| ---------------------- | ----------------- | ------- | ----------------------------------------------- |
| `execute`              | boolean or object | `false` | Enable POST `/execute` endpoint for DQL queries |
| `presence`             | boolean or object | `false` | Enable GET `/presence` endpoint                 |
| `get_logs`             | boolean or object | `false` | Enable GET `/logs` endpoint                     |
| `attachments_upload`   | boolean or object | `false` | Enable attachment upload endpoints              |
| `attachments_download` | boolean or object | `false` | Enable attachment download endpoints            |

#### Endpoint Request Limits Object

When using object form for an endpoint:

| Field                    | Type    | Default | Description                                        |
| ------------------------ | ------- | ------- | -------------------------------------------------- |
| `enabled`                | boolean | `false` | Whether this endpoint is enabled                   |
| `max_header_count`       | integer | null    | Override max header count for this endpoint        |
| `max_header_size_bytes`  | integer | null    | Override max header size for this endpoint         |
| `max_request_line_bytes` | integer | null    | Override max request line size for this endpoint   |
| `max_body_size_mb`       | integer | null    | Override max body size for this endpoint (0-65535) |

## API Endpoints

All endpoints are served directly from the listen address (no base path prefix).

### Execute Endpoint

**Path**: `POST /execute`

Execute DQL queries against the database.

Request body:

```json theme={null}
{
  "query": "SELECT * FROM collection WHERE field = :value",
  "args": {
    "value": "example"
  }
}
```

Optional headers:

* **Timeout header**: Specify custom timeout for the request

Response:

* **Success (200)**: Query results in JSON format
* **Error (4xx/5xx)**: Error details with appropriate HTTP status code

### Health Check Endpoint

**Path**: `GET /health`

Simple health check that returns HTTP 200 if the server is running.

### Presence Endpoint

**Path**: `GET /presence`

Get information about connected peers and their presence status.

### Logs Endpoint

**Path**: `GET /logs`

Retrieve logs from the Edge Server and Ditto SDK.

### Attachments Endpoints

**Upload**: Upload new attachments to the database
**Download**: Retrieve attachments from the database

## Complete Examples

### Basic HTTP Server

```yaml theme={null}
database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-api-server"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "__playgroundProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config: dev_mode
  http_api: true
  enable_healthcheck: true

auth: dev_mode
```

Access the API at: `http://127.0.0.1:8080/execute`

### HTTP Server with TLS

```yaml theme={null}
database:
  db_id: "87654321-4321-4123-4321-210987654321"
  device_name: "api-gateway"
  auth:
    small_peer_only:
      offline_license_token: "YOUR_LICENSE"

http_server:
  listen_addr: "localhost:3000"
  tls_config:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"
  http_api: true

auth: dev_mode
```

Access the API at: `https://localhost:3000/execute`

### Health Check Only Server

Minimal configuration for monitoring:

```yaml theme={null}
database:
  db_id: "33333333-3333-4333-3333-333333333333"
  device_name: "monitor"
  auth:
    small_peer_only:
      offline_license_token: "MONITOR_LICENSE"

http_server:
  listen_addr: "127.0.0.1:9090"
  tls_config: dev_mode
  http_api: false  # Disable all API endpoints
  enable_healthcheck: true  # Enable health checks only

auth: dev_mode
```

Access health check at: `http://127.0.0.1:9090/health`

### Advanced Configuration with Fine-Grained Control

```yaml theme={null}
database:
  db_id: "44444444-4444-4444-4444-444444444444"
  device_name: "production-server"
  auth:
    server:
      access_token: "TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "customProvider"

http_server:
  listen_addr: "127.0.0.1:8080"
  tls_config:
    cert: "/path/to/cert.pem"
    key: "/path/to/key.pem"
  request_timeout_ms: 30000  # 30 second timeout
  enable_healthcheck: true
  serve_docs: true
  http_api:
    execute:
      enabled: true
      max_body_size_mb: 10
    presence: true
    get_logs: true
    attachments_upload:
      enabled: true
      max_body_size_mb: 50
    attachments_download: true

auth: dev_mode
```

## Using the HTTP API

### Query Execution Example

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

# Update data
curl -X POST http://127.0.0.1:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "query": "UPDATE users SET age = :new_age WHERE id = :user_id",
    "args": {
      "user_id": "user123",
      "new_age": 26
    }
  }'
```

### Health Check Example

```bash theme={null}
# Check server health
curl -I http://127.0.0.1:8080/health

# Response:
# HTTP/1.1 200 OK
```

## Security Considerations

While Ditto Edge Server is in private preview, no deployments should be considered secure. Use is for development purposes only.

## Important Notes

* **Single Database**: Edge Server supports one database per instance
* **Port Conflicts**: Ensure the HTTP server port doesn't conflict with other services
* **Restart Required**: Changes to HTTP server configuration require Edge Server restart
* **IPv6 Support**: Use bracketed notation for IPv6 addresses (e.g., `"[::1]:8080"`)
* **TLS Required**: The `tls_config` field is required - use `dev_mode` for HTTP or provide certificate/key for HTTPS

## Related Resources

* [DittoDatabase Configuration](/edge-server/configuration/reference/ditto-database-resource)
* [Ditto Query Language (DQL)](/dql/dql)
* [Edge Server Install Guide](/edge-server/install-guide)