API Reference

The Voltis daemon exposes a RESTful HTTP API for programmatic control. It listens on a configurable port (default: 4650) and uses JSON for responses. This API powers the CLI but can be used directly with tools like curl, Postman, or custom clients.

The API is stateless where possible, with all state managed in the backend SQLite database.

Base URL: http://<host>:<port> (e.g., http://localhost:4650).

Common Headers and Formats

• Request Headers:
  • Content-Type: application/json for JSON payloads.
  • Content-Type: multipart/form-data for file uploads (workload pushes).
• Response Formats:
  • Success: 200 OK with JSON body (arrays/objects).
  • Errors: 4xx/5xx with JSON { "error": "detailed message" }.
  • Streaming: Some endpoints (e.g., logs) use text/plain.

Authentication and Security

• No Built-in Auth: All endpoints are open. Implement at the network level.
• Recommendations:
  • Use HTTPS (TLS termination via proxy).
  • IP whitelisting for edge nodes.
  • API keys via custom middleware (extend pkg/api/server.go).
• CORS: Enabled for * origins (development only; restrict in prod).

Endpoints

Endpoints are grouped by resource. All GET requests return JSON arrays of list items.

Health and Ping

• GET /health

  • Description: Basic health check.
  • Response: 200 OK (empty body).
  • Use: Monitoring/heartbeat.

• POST /ping

  • Description: Echo test for connectivity.
  • Request Body: Plain text “ping”.
  • Response: 200 OK with body “pong”.
  • Example:

    curl -X POST http://localhost:4650/ping -d "ping"

Workload Management

Workloads are the primary resource. Digests are SHA-256 hashes for integrity.

• GET /workload

  • Description: List all stored workloads.
  • Response: 200 OK, array of Workloads:

    [
      {
        "name": "my-workload",
        "digest": "sha256:abc123...",
        "active": true,
        "reconcile": true,
        "message": ""
      }
    ]
  • Fields: name (string), digest (string), active (bool), reconcile (bool), message (string).

• POST /workload/{name}/status/{status}

  • Description: Push and install a workload tarball. {status} is “active” or “inactive”.
  • Path Params: name (workload ID), status (active/inactive).
  • Request: Multipart form with file key (gzipped tarball).
  • Response: 200 OK
  • Behavior: Extracts tarball, validates structure, runs install tasks. Overwrites if name exists.
  • Example:

    curl -X POST "http://localhost:4650/workload/my-workload/status/active" \
      -F "[email protected]"
  • Errors: 400 if invalid tarball; 409 if digest mismatch.

• POST /active/{name}

  • Description: Activate a stored workload (deactivates current if any).
  • Path Params: name (workload name)
  • Response: 200 OK
  • Behavior: Runs state tasks for services; updates active flag in DB.
  • Errors: 404 if workload not found.

• POST /reconcile/status/{status}

  • Description: Changes reconcile on the active workload.
  • Path Params: status (start|stop)
  • Response: 200 OK
  • Behavior: Modifies the reconcile status on the active workload; updates in DB
  • Errors: 404 if no active workload.

• POST /reset

  • Description: Deactivate and uninstall the active workload.
  • Response: 200 OK
  • Behavior: Runs uninstall tasks; clears active state.
  • Errors: 404 if no active workload.

• DELETE /workload/{name}

  • Description: Remove the workload and uninstall if it is the active workload.
  • Response: 200 OK
  • Behavior: Removes workload from database; Runs uninstall tasks (if applicable); clears active state (if applicable).
  • Errors: 404 if workload not found.

Service Management

Services represent runtime components (e.g., systemd units).

• GET /service
  • Description: List all services from active workload.
  • Response: 200 OK, array of ServiceListItem:

    [
      {
        "name": "docker",
        "currentState": "running",
        "desiredState": "active",
        "installed": true,
        "message": ""
      }
    ]
  • Fields: name (string), currentState (enum: running/stopped/failed), desiredState (active/inactive), installed (bool), message (string).

Package Management

Packages are installable artifacts (e.g., debs).

• GET /package
  • Description: List installed packages.
  • Response: 200 OK, array of Packages:

    [
      {
        "name": "docker-ce",
        "installed": true,
        "message": ""
      }
    ]

Job Management

Jobs are tasks executed during deployment or on an interval.

• GET /job
  • Description: List jobs.
  • Response: 200 OK, array of Jobs:

    [
      {
        "name": "backup",
        "message": "",
        "completed": true,
        "continuous": false
      }
    ]

Component Overview

• GET /components
  • Description: Aggregated view of services + packages + jobs.
  • Response: 200 OK, JSON object with arrays for each.

Error Handling

Common errors:

• 400 Bad Request: Invalid input (e.g., malformed JSON/tarball).
• 404 Not Found: Resource missing (e.g., unknown workload).
• 500 Internal Server Error: Daemon issue (e.g., DB lock); check logs.

Client Implementation

The CLI that can be installed via task install contains commands to interface with this API.

Rate Limiting and Performance

• No built-in limits; implement in proxy.
• Endpoints are lightweight; database queries are optimized for edge devices (SQLite).

For production scaling, consider multiple daemons with shared storage (future feature).

Next: Troubleshooting