/api/raida/version

GET

Queries all 25 RAIDA servers for their version information (software build date).

Description

The `/api/raida/version` endpoint sends Version (Command 0x0065) requests to all 25 RAIDA servers in parallel to retrieve their current software version. The version is represented as a build date in YYYYMMDD format and is converted to a human-readable string (e.g., "2025-January-15").

This endpoint is fully implemented and production-ready. It uses multi-threaded execution to query all 25 RAIDAs simultaneously, providing results in 1-2 seconds instead of 25+ seconds for sequential queries.

💡 Use Case

This endpoint is perfect for:

  • Monitoring RAIDA network health and version consistency
  • Verifying all RAIDAs are running the same software version
  • Tracking RAIDA software updates and deployment status
  • Identifying outdated or malfunctioning RAIDA nodes
  • Network diagnostics and troubleshooting
â„šī¸ RAIDA Version Protocol

Command: 0x0065 (Version / Command 101)

Request Format: Challenge(16 bytes) + Terminator(0x3E3E)

Response Format: YYYYMMDD(8 bytes ASCII) + Terminator(0x3E3E)

Version Format: 8 ASCII characters representing the software build date

Example: "20250115" is parsed and displayed as "2025-January-15"

Parameters

This endpoint does not require any parameters.

🔓 Public Endpoint

No authentication required. The Version command is a public RAIDA operation.

Response

Returns a JSON object with version information from all 25 RAIDA servers and overall statistics.

Response Properties

status string
Either "success" if operation completed, or "error" if task creation/execution failed.
operation string
Always "raida_version".
task_id string
Unique task identifier in format "Jan-31-25_03-45-12-PM". Used for receipt tracking.
pass_count integer
Number of RAIDAs that responded with valid version data.
fail_count integer
Always 0 for this operation (no authentication failure possible).
error_count integer
Number of RAIDAs that returned error codes or invalid version data.
timeout_count integer
Number of RAIDAs that didn't respond within the timeout period (typically 5000ms).
raida_versions array
Array of 25 objects, one for each RAIDA server, containing version details.

RAIDA Version Object Properties

raida_id integer
RAIDA server number (0-24).
status string
Response status: "pass" (valid version), "timeout" (no response), "no_response" (connection failed), "error" (RAIDA error), or "invalid_version" (unparseable date).
version string
Human-readable version string (e.g., "2025-January-15"), or error message if status is not "pass".
raw_version string
Raw 8-character version string received from RAIDA (e.g., "20250115"). Empty if no valid response.

Example Success Response

{
  "status": "success",
  "operation": "raida_version",
  "task_id": "Jan-31-25_03-45-12-PM",
  "pass_count": 24,
  "fail_count": 0,
  "error_count": 0,
  "timeout_count": 1,
  "raida_versions": [
    {
      "raida_id": 0,
      "status": "pass",
      "version": "2025-January-15",
      "raw_version": "20250115"
    },
    {
      "raida_id": 1,
      "status": "pass",
      "version": "2025-January-15",
      "raw_version": "20250115"
    },
    {
      "raida_id": 2,
      "status": "timeout",
      "version": "Request timed out",
      "raw_version": ""
    },
    ...
    {
      "raida_id": 24,
      "status": "pass",
      "version": "2025-January-15",
      "raw_version": "20250115"
    }
  ]
}

Example Error Response

{
  "status": "error",
  "operation": "raida_version",
  "message": "Failed to create RAIDA task"
}

Version Validation

The endpoint validates version data received from RAIDAs to ensure it represents a valid date:

Validation Rules

Year Range 2020-2099
Version year must be between 2020 and 2099.
Month Range 1-12
Month must be valid (01-12).
Day Range 1-31
Day must be valid (01-31).
âš ī¸ Invalid Version Data

If a RAIDA responds with data that doesn't parse as a valid date, the status will be "invalid_version" and the version field will contain an error message. The raw_version field will contain the unparseable data for debugging purposes.

Examples

JavaScript (fetch)

const API_HOST = 'http://localhost:8080';

async function getRaidaVersions() {
    try {
        const response = await fetch(`${API_HOST}/api/raida/version`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Task ID: ${result.task_id}`);
            console.log(`Pass Count: ${result.pass_count}/25`);
            console.log(`Timeout Count: ${result.timeout_count}`);
            console.log(`Error Count: ${result.error_count}`);
            console.log('\nRAIDA Versions:');

            // Group RAIDAs by version
            const versionMap = new Map();
            result.raida_versions.forEach(raida => {
                if (raida.status === 'pass') {
                    const version = raida.version;
                    if (!versionMap.has(version)) {
                        versionMap.set(version, []);
                    }
                    versionMap.get(version).push(raida.raida_id);
                }
            });

            // Display grouped results
            versionMap.forEach((raidas, version) => {
                console.log(`${version}: RAIDAs ${raidas.join(', ')}`);
            });

            // Show any problematic RAIDAs
            const problematic = result.raida_versions.filter(
                r => r.status !== 'pass'
            );
            if (problematic.length > 0) {
                console.log('\nProblematic RAIDAs:');
                problematic.forEach(r => {
                    console.log(`R${r.raida_id}: ${r.status} - ${r.version}`);
                });
            }
        } else {
            console.error('Error:', result.message);
        }
    } catch (error) {
        console.error('Network error:', error);
    }
}

getRaidaVersions();

cURL

# Get RAIDA versions
curl -X GET "http://localhost:8080/api/raida/version"

# Pretty-print JSON response (requires jq)
curl -s -X GET "http://localhost:8080/api/raida/version" | jq .

# Show only pass count and task ID
curl -s -X GET "http://localhost:8080/api/raida/version" | \
    jq '{task_id: .task_id, pass_count: .pass_count, timeout_count: .timeout_count}'

# List all RAIDA versions
curl -s -X GET "http://localhost:8080/api/raida/version" | \
    jq '.raida_versions[] | "R\(.raida_id): \(.version)"'

Go

package main

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

const ApiHost = "http://localhost:8080"

type RaidaVersion struct {
    RaidaID    int    `json:"raida_id"`
    Status     string `json:"status"`
    Version    string `json:"version"`
    RawVersion string `json:"raw_version"`
}

type VersionResponse struct {
    Status         string         `json:"status"`
    Operation      string         `json:"operation"`
    TaskID         string         `json:"task_id"`
    PassCount      int            `json:"pass_count"`
    FailCount      int            `json:"fail_count"`
    ErrorCount     int            `json:"error_count"`
    TimeoutCount   int            `json:"timeout_count"`
    RaidaVersions  []RaidaVersion `json:"raida_versions"`
}

func main() {
    resp, err := http.Get(fmt.Sprintf("%s/api/raida/version", ApiHost))
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)

    var result VersionResponse
    if err := json.Unmarshal(body, &result); err != nil {
        panic(err)
    }

    if result.Status == "success" {
        fmt.Printf("Task ID: %s\n", result.TaskID)
        fmt.Printf("Pass Count: %d/25\n", result.PassCount)
        fmt.Printf("Timeout Count: %d\n", result.TimeoutCount)
        fmt.Printf("Error Count: %d\n\n", result.ErrorCount)

        // Group by version
        versionMap := make(map[string][]int)
        for _, raida := range result.RaidaVersions {
            if raida.Status == "pass" {
                versionMap[raida.Version] = append(
                    versionMap[raida.Version],
                    raida.RaidaID,
                )
            }
        }

        fmt.Println("RAIDA Versions:")
        for version, raidas := range versionMap {
            fmt.Printf("%s: RAIDAs %v\n", version, raidas)
        }

        // Show problematic RAIDAs
        hasProblems := false
        for _, raida := range result.RaidaVersions {
            if raida.Status != "pass" {
                if !hasProblems {
                    fmt.Println("\nProblematic RAIDAs:")
                    hasProblems = true
                }
                fmt.Printf("R%d: %s - %s\n",
                    raida.RaidaID,
                    raida.Status,
                    raida.Version,
                )
            }
        }
    } else {
        fmt.Printf("Error: %s\n", result.Status)
    }
}

Performance

This endpoint uses multi-threaded RAIDA execution for optimal performance:

Execution Characteristics

Execution Mode Parallel
All 25 RAIDAs are queried simultaneously using a thread pool.
Typical Response Time 1-2 seconds
Total time includes network RTT and RAIDA processing for all 25 servers in parallel.
Per-RAIDA Timeout 5000ms
Each RAIDA has 5 seconds to respond. Non-responsive RAIDAs are marked as "timeout".
Performance Gain 20-25x faster
Compared to sequential execution (which would take 25+ seconds).

Interpreting Results

✅ Healthy Network

Expected: 23-25 RAIDAs respond with "pass" status and identical versions.

A healthy RAIDA network should have all or nearly all servers running the same software version. Occasional timeouts (1-2 RAIDAs) are normal due to network latency.

âš ī¸ Version Mismatch

Warning Sign: Multiple different versions across RAIDAs.

This may indicate a rolling update in progress or partial deployment. Wait for all RAIDAs to converge to the same version, or contact RAIDA administrators if the mismatch persists.

❌ Network Issues

Problem: More than 3-4 timeouts or errors.

This indicates potential network connectivity problems or RAIDA server issues. Check your internet connection and verify RAIDA network status. If issues persist, some CloudCoin operations may fail or be unreliable.

Related Endpoints

/api/program/echo

Test basic RAIDA connectivity with health check pings to all 25 servers.

/api/raida/countcoins

Query each RAIDA for the total number of coins stored in their database.

/api/transactions/task

Query the status and results of any task using its task_id.