/servers

GET SYNC

Retrieve a list of all RAIDA servers with their connection information and availability status.

GET /api/data/servers

Description

The `/servers` endpoint provides comprehensive information about all RAIDA servers in the network. It returns details including server IDs, addresses, ports, and availability status. This endpoint is useful for monitoring the health of the RAIDA network and determining which servers are currently operational.

Server Availability

By default, only available servers are returned. Use the `include_unavailable` parameter to retrieve the complete list including offline servers.

Query Parameters

Parameter Type Required Default Description
include_unavailable boolean No false When set to true, includes servers that are currently unavailable or offline in the response.

Response

Returns a 200 OK response with a JSON object containing the server list and metadata.

Response Properties

servers array<object>
An array of server objects, each containing server information.
count integer
The total number of servers returned in the response.
include_unavailable boolean
Indicates whether unavailable servers are included in the results.

Server Object Properties

server_id string
The unique identifier for the server (e.g., "RAIDA0", "RAIDA1").
address string
The hostname or IP address of the server.
port integer
The port number used to connect to the server.
is_available boolean
Indicates whether the server is currently online and accepting connections.

Example Response

{
  "servers": [
    {
      "server_id": "RAIDA0",
      "address": "raida0.cloudcoin.global",
      "port": 443,
      "is_available": true
    },
    {
      "server_id": "RAIDA1",
      "address": "raida1.cloudcoin.global",
      "port": 443,
      "is_available": true
    },
    {
      "server_id": "RAIDA2",
      "address": "raida2.cloudcoin.global",
      "port": 443,
      "is_available": false
    }
  ],
  "count": 3,
  "include_unavailable": true
}

Try It Out

http://localhost:8080/api/data/servers

Examples

JavaScript (async/await)

const API_BASE = 'http://localhost:8080/api';

async function getServers(includeUnavailable = false) {
    try {
        const url = new URL(`${API_BASE}/data/servers`);
        if (includeUnavailable) {
            url.searchParams.append('include_unavailable', 'true');
        }

        const response = await fetch(url);
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log(`Found ${data.count} servers:`);

        data.servers.forEach(server => {
            const status = server.is_available ? 'Online' : 'Offline';
            console.log(`${server.server_id}: ${server.address}:${server.port} [${status}]`);
        });

        return data;
    } catch (error) {
        console.error('Error fetching servers:', error);
    }
}

// Get all servers including unavailable
getServers(true);

cURL

# Get available servers only
curl -X GET "http://localhost:8080/api/data/servers"

# Get all servers including unavailable
curl -X GET "http://localhost:8080/api/data/servers?include_unavailable=true"

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

const ApiBase = "http://localhost:8080/api"

type Server struct {
    ServerID    string `json:"server_id"`
    Address     string `json:"address"`
    Port        int    `json:"port"`
    IsAvailable bool   `json:"is_available"`
}

type ServersResponse struct {
    Servers            []Server `json:"servers"`
    Count              int      `json:"count"`
    IncludeUnavailable bool     `json:"include_unavailable"`
}

func getServers(includeUnavailable bool) (*ServersResponse, error) {
    url := fmt.Sprintf("%s/data/servers", ApiBase)
    if includeUnavailable {
        url += "?include_unavailable=true"
    }

    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result ServersResponse
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    servers, err := getServers(true)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Found %d servers:\n", servers.Count)
    for _, server := range servers.Servers {
        status := "Offline"
        if server.IsAvailable {
            status = "Online"
        }
        fmt.Printf("%s: %s:%d [%s]\n",
            server.ServerID, server.Address, server.Port, status)
    }
}

Related Endpoints

/admin/servers/parity

Get the current parity server configuration for the QMail system.

View Details

/admin/sync

Manually trigger a data synchronization from the RAIDA network.

View Details