{
  "name": "CacheSync API",
  "version": "2.4.1",
  "description": "Distributed cache synchronization service with automatic peer discovery.",
  "base_url": "https://cache.ergasterion.io",
  "endpoints": {
    "GET /v1/health": {
      "description": "Check cluster health and node status.",
      "returns": "Cluster health summary including node count and uptime."
    },
    "GET /v1/stats": {
      "description": "Retrieve cache statistics including hit rate, memory usage, and per-node key distribution.",
      "returns": "JSON object with cache metrics."
    },
    "POST /v1/sync": {
      "description": "Register a new node or update an existing node's configuration in the cluster.",
      "parameters": {
        "node_id": "string — unique node identifier (e.g. hostname or UUID)",
        "region": "string — geographic region (e.g. eu-central-1)",
        "capabilities": "array — supported cache operations (e.g. [\"get\", \"set\", \"delete\"])",
        "context": "object — node context including hostname, version, and runtime info"
      },
      "example": {
        "method": "POST",
        "url": "https://cache.ergasterion.io/v1/sync",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "node_id": "my-cache-node",
          "region": "eu-central-1",
          "capabilities": [
            "get",
            "set",
            "delete",
            "flush"
          ],
          "context": {
            "hostname": "cache.example.com",
            "version": "2.4.1",
            "runtime": "python3.11"
          }
        }
      }
    },
    "POST /v1/heartbeat": {
      "description": "Send periodic health updates from a registered node. Recommended interval: every 30 seconds.",
      "parameters": {
        "node_id": "string — the node identifier registered via /v1/sync",
        "status": "string — current node status (active, degraded, draining)",
        "load": "number — current load factor (0.0-1.0)",
        "context": "object — runtime context including active connections and memory pressure"
      },
      "example": {
        "method": "POST",
        "url": "https://cache.ergasterion.io/v1/heartbeat",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "node_id": "my-cache-node",
          "status": "active",
          "load": 0.34,
          "context": {
            "connections": 42,
            "memory_pressure": "low",
            "hostname": "cache.example.com",
            "version": "2.4.1"
          }
        }
      }
    }
  },
  "quickstart": "1. Register your node with POST /v1/sync. 2. Send health updates every 30s via POST /v1/heartbeat. 3. Monitor cluster health with GET /v1/health."
}