REST API Reference¶

Pleiades exposes a REST API for managing pools, members, services, health checks, and geo rules. Enable it via api.enabled: true in your config.

Base URL: http://<listenAddr>:<port>/api/v1

All request and response bodies are JSON. Successful list endpoints return [] (not null) when empty.

Health¶

GET /api/v1/health¶

Returns server liveness.

Response 200:

{"status": "ok"}

Pools¶

A pool is a named group of backend members.

POST /api/v1/pools¶

Create a pool.

Request:

{"name": "web"}

Response 201:

{"id": "a1b2c3...", "name": "web"}

Errors: - 400 — name missing or empty.

GET /api/v1/pools¶

List all pools.

Response 200:

[{"id": "a1b2c3...", "name": "web"}]

GET /api/v1/pools/{id}¶

Get a pool by ID.

Response 200: Pool object. Response 404: pool not found.

PUT /api/v1/pools/{id}¶

Rename a pool.

Request:

{"name": "web-v2"}

Response 200: updated Pool object. Response 400 — name missing. Response 404 — pool not found.

DELETE /api/v1/pools/{id}¶

Delete a pool. Cascades to members, health checks, and geo rules.

Response 204: no content. Response 404: pool not found.

Members¶

A member is a backend server (IP + port + weight) belonging to a pool.

POST /api/v1/pools/{id}/members¶

Add a member to a pool. Also adds the endpoint to the running balancer.

Request:

{"ipAddress": "10.0.0.1", "port": 80, "weight": 3, "priority": 1}

Fields: - ipAddress (string, required): valid IPv4 or IPv6 address. - port (int, required): 1–65535. - weight (int, optional): default 1 if ≤ 0. Used by weighted-round-robin. - priority (int, optional): default 0 (unset). Used by the failover algorithm — lower number = higher preference (1 = primary, 2 = secondary, …). 0 sorts last.

Response 201:

{"id": "...", "poolId": "...", "ipAddress": "10.0.0.1", "port": 80, "weight": 3, "priority": 1, "enabled": true}

Errors: - 400 — invalid IP or port out of range. - 404 — pool not found (on internal lookup failure).

GET /api/v1/pools/{id}/members¶

List members in a pool.

Response 200: array of Member objects.

GET /api/v1/members/{id}¶

Get a member by ID.

Response 200: Member object. Response 404: member not found.

PUT /api/v1/members/{id}¶

Update a member's weight, priority, and enabled state. Reflects the change in the running balancer immediately (weight set to 0 if disabled).

Request:

{"weight": 1, "priority": 2, "enabled": true}

Fields: - weight (int): negative values coerced to 0. - priority (int): failover preference order (1 = primary, 2 = secondary, …; 0 = unset/last-resort). - enabled (bool).

Response 200: updated Member object. Response 404: member not found.

DELETE /api/v1/members/{id}¶

Delete a member. Removes the endpoint from the running balancer.

Response 204: no content. Response 404: member not found.

Services¶

A service binds a DNS name + domain to a pool and a load balancing algorithm.

POST /api/v1/services¶

Create a service.

Request:

{"name": "www", "domain": "example.com.", "algorithm": "round-robin", "ttl": 60, "poolId": null}

Fields: - name (string, required). - domain (string, required): fully-qualified DNS name (include trailing dot). - algorithm (string, optional): one of round-robin (default), weighted-round-robin, geo-ip, map-file, failover. - ttl (int, optional): DNS TTL in seconds. Default 60. - poolId (string | null, optional): ID of the pool to attach.

Response 201:

{"id": "...", "name": "www", "domain": "example.com.", "algorithm": "round-robin", "poolId": null}

Errors: - 400 — name or domain missing.

GET /api/v1/services¶

List all services.

Response 200: array of Service objects.

GET /api/v1/services/{id}¶

Get a service by ID.

Response 200: Service object. Response 404: not found.

PUT /api/v1/services/{id}¶

Update a service.

Request: same fields as POST.

Response 200: updated Service object. Response 400 — name or domain missing. Response 404 — service not found.

DELETE /api/v1/services/{id}¶

Delete a service.

Response 204: no content. Response 404: not found.

Health Checks¶

Each pool can have at most one health check configuration (upsert semantics).

PUT /api/v1/pools/{id}/healthcheck¶

Create or replace the health check for a pool.

Request:

{
  "type": "http",
  "port": 443,
  "intervalMs": 5000,
  "timeoutMs": 1000,
  "httpPath": "/ping",
  "httpHost": "",
  "httpExpectedStatus": 200,
  "httpContains": "",
  "tls": true,
  "insecureSkipVerify": false,
  "scoreWindow": 0
}

Fields (all optional — defaults applied for zero values): - type (string): tcp or http. Default tcp. - port (int): default 80. - intervalMs (int): milliseconds between checks. Default 10000. - timeoutMs (int): check timeout milliseconds. Default 2000. - httpPath (string): HTTP request path. Default /. - httpHost (string): HTTP Host header override. - httpExpectedStatus (int): expected HTTP status. Default 200. - httpContains (string): required response body substring. - tls (bool): use HTTPS. - insecureSkipVerify (bool): skip TLS certificate verification. - scoreWindow (int): rolling probe window for partial health scoring. 0 (default) = disabled; N = score over last N probes (0.0–1.0). See Health Checks for details.

Response 200: HealthCheck object.

GET /api/v1/pools/{id}/healthcheck¶

Get the health check for a pool.

Response 200: HealthCheck object. Response 404: no health check configured for this pool.

DELETE /api/v1/pools/{id}/healthcheck¶

Delete the health check for a pool.

Response 204: no content. Response 404: no health check found.

Geo Rules¶

Geo rules map source CIDR blocks to preferred endpoint IPs for a pool.

POST /api/v1/pools/{id}/georules¶

Create a geo rule.

Request:

{"cidr": "10.0.0.0/8", "endpoint": "203.0.113.1", "priority": 5}

Fields: - cidr (string, required): valid CIDR block. - endpoint (string, required): valid IP address. - priority (int, optional): lower values = higher priority (convention; not enforced by storage).

Response 201:

{"id": "...", "poolId": "...", "cidr": "10.0.0.0/8", "endpoint": "203.0.113.1", "priority": 5}

Errors: - 400 — invalid CIDR or invalid endpoint IP.

GET /api/v1/pools/{id}/georules¶

List geo rules for a pool.

Response 200: array of GeoRule objects.

DELETE /api/v1/georules/{id}¶

Delete a geo rule by ID.

Response 204: no content. Response 404: rule not found.

Error responses¶

All error responses have the form:

{"error": "description"}

Common status codes: - 400 Bad Request — validation failure (invalid IP, port, CIDR, missing required field). - 404 Not Found — resource does not exist. - 500 Internal Server Error — unexpected database or server error.

Running the API server¶

api:
  enabled: true
  listenAddr: "127.0.0.1"
  port: 8080
  webuiPath: "/opt/gslb/webui"  # Optional: path to Next.js static export output (webui/out/)

The server starts as a goroutine alongside the DNS server. Shut down is graceful (context cancellation). Set listenAddr: "0.0.0.0" to expose on all interfaces (ensure firewall rules are in place).

Dashboard Endpoints¶

GET /api/v1/dashboard/stats¶

Returns aggregated statistics for the dashboard.

Response 200:

{
  "totalPools": 3,
  "totalMembers": 12,
  "healthyMembers": 10,
  "unhealthyMembers": 2,
  "totalServices": 5,
  "totalGeoRules": 8,
  "uptimeSeconds": 86400,
  "webSocketClients": 2
}

GET /api/v1/snapshot¶

Returns the full current state of the GSLB system. Used for initial load of the WebUI.

Response 200:

{
  "pools": [...],
  "members": {"pool-id-1": [...]},
  "services": [...],
  "healthStatus": {"pool-id-1": {"192.168.1.1": {"healthy": true, "score": 1.0, "lastChecked": 1234567890}}},
  "geoRules": {"pool-id-1": [...]},
  "stats": {...},
  "timestamp": 1234567890000
}

WebSocket¶

GET /api/v1/ws/token¶

Generates a JWT token for WebSocket authentication. Include this token when connecting to the WebSocket endpoint.

Response 200:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": 1234567890000
}

WebSocket Connection¶

Connect to ws://<host>:<port>/api/v1/ws?token=<token>

The WebSocket connection provides real-time updates for: - Health status changes (members going online/offline) - Pool, member, and service CRUD operations - Dashboard statistics updates

Message Types¶

Health Update:

{
  "type": "health_update",
  "payload": {
    "poolId": "pool-123",
    "ipAddress": "192.168.1.1",
    "healthy": true,
    "score": 1.0,
    "timestamp": 1234567890000,
    "rttMs": 5,
    "node": "node-1"
  }
}

Pool Update:

{
  "type": "pool_update",
  "payload": {
    "action": "created|updated|deleted",
    "pool": {...}
  }
}

Member Update:

{
  "type": "member_update",
  "payload": {
    "action": "created|updated|deleted|snapshot",
    "poolId": "pool-123",
    "member": {...}
  }
}

Service Update:

{
  "type": "service_update",
  "payload": {
    "action": "created|updated|deleted",
    "service": {...}
  }
}

WebUI¶

The WebUI is a Next.js-based dashboard for managing the GSLB system. It connects to the REST API and WebSocket for real-time updates.

Enabling the WebUI¶

1. Build the Next.js application:

   cd webui
   npm install
   npm run build
   

2. Configure the WebUI path in config.yaml:

   api:
     enabled: true
     listenAddr: "0.0.0.0"
     port: 8080
     webuiPath: "/opt/gslb/webui"
   

3. Access the WebUI at http://<host>:<port>/ui/

WebUI Features¶

• Dashboard: Real-time overview of all pools and their health status
• Pool Management: Create, view, and manage pools
• Member Management: Add, update, and remove pool members
• Health Monitoring: Real-time health status updates via WebSocket
• Activity Feed: Live feed of health changes and configuration updates