/api/system/version-check

GET

Check whether a newer version of the CloudCoin REST Core client software is available.

http://localhost:8080/api/system/version-check

Description

The /api/system/version-check endpoint is the single authority the GUI should call at startup to determine whether the REST Core client needs updating. It compares the locally installed version against the latest published version from the CloudCoin network.

The endpoint fetches the latest published client version from the RAIDA network using a 2-of-3 consensus mechanism (querying 3 random RAIDA servers and requiring 2 matching responses). It then compares the remote version against the local build version and reports whether an update is available.

Client Version vs. RAIDA Server Version

This endpoint checks the version of the local REST Core client software (the program running on your machine). It does not check the version of the RAIDA server software. To query RAIDA server versions, use /api/raida/version instead.

Version Format

All versions use the YYYY-MM-DD date format (e.g., 2026-04-08). This format is shared between the local build version and the remote authority, making comparison straightforward.

Failure Handling

If the endpoint cannot reach the RAIDA network or no consensus is achieved, it returns "success": false with an error message. It does not falsely report "up to date" when the check fails. The GUI should handle this case by informing the user that the update check could not be completed.

Parameters

This endpoint does not require any parameters.

Response

Returns a JSON object indicating whether an update is available, or whether the check failed.

Response Properties (Success)

success boolean
true when the version check completed successfully (RAIDA consensus reached).
program string
Program name. Always "CloudCoin REST Core".
current_version string
The locally installed version in YYYY-MM-DD format (e.g., "2026-04-08").
latest_version string
The latest published version from the RAIDA network in YYYY-MM-DD format. Only present when success is true.
update_available boolean
true if latest_version is newer than current_version. Only present when success is true.
message string
Human-readable status message.

Example Response (Update Available)

{
  "success": true,
  "program": "CloudCoin REST Core",
  "current_version": "2026-04-08",
  "latest_version": "2026-04-15",
  "update_available": true,
  "message": "A newer version is available. Please update."
}

Example Response (Up to Date)

{
  "success": true,
  "program": "CloudCoin REST Core",
  "current_version": "2026-04-08",
  "latest_version": "2026-04-08",
  "update_available": false,
  "message": "You are running the latest version"
}

Example Response (Check Failed)

{
  "success": false,
  "program": "CloudCoin REST Core",
  "current_version": "2026-04-08",
  "message": "Could not check for updates (unable to reach update servers)"
}

Examples

JavaScript (fetch)

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

async function checkForUpdates() {
    try {
        const response = await fetch(`${API_HOST}/api/system/version-check`);
        const result = await response.json();

        if (!result.success) {
            console.warn('Update check failed:', result.message);
            // Show user a non-blocking warning
            return;
        }

        console.log(`Current version: ${result.current_version}`);
        console.log(`Latest version:  ${result.latest_version}`);

        if (result.update_available) {
            console.log('Update available! Please download the latest version.');
            // Prompt user to update
        } else {
            console.log('You are running the latest version.');
        }
    } catch (error) {
        console.error('Error checking for updates:', error);
    }
}

// Call on application startup
checkForUpdates();

cURL

# Check for updates
curl -X GET "http://localhost:8080/api/system/version-check"

# Pretty-print with jq
curl -s "http://localhost:8080/api/system/version-check" | jq

# Check if update is available (returns true/false)
curl -s "http://localhost:8080/api/system/version-check" | jq '.update_available'

# Get just the current version
curl -s "http://localhost:8080/api/system/version-check" | jq -r '.current_version'

# Check if the version check itself succeeded
curl -s "http://localhost:8080/api/system/version-check" | jq '.success'

Go

package main

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

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

type VersionCheckResponse struct {
    Success         bool   `json:"success"`
    Program         string `json:"program"`
    CurrentVersion  string `json:"current_version"`
    LatestVersion   string `json:"latest_version,omitempty"`
    UpdateAvailable bool   `json:"update_available,omitempty"`
    Message         string `json:"message"`
}

func main() {
    resp, err := http.Get(fmt.Sprintf("%s/api/system/version-check", ApiHost))
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    defer resp.Body.Close()

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

    var result VersionCheckResponse
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Printf("Error parsing JSON: %v\n", err)
        return
    }

    if !result.Success {
        fmt.Printf("Update check failed: %s\n", result.Message)
        fmt.Printf("Current version: %s\n", result.CurrentVersion)
        return
    }

    fmt.Printf("Current version: %s\n", result.CurrentVersion)
    fmt.Printf("Latest version:  %s\n", result.LatestVersion)

    if result.UpdateAvailable {
        fmt.Println("An update is available! Please download the latest version.")
    } else {
        fmt.Println("You are running the latest version.")
    }
}

Implementation Details

How It Works

  1. The endpoint reads the local build version (compiled into the program as a YYYY-MM-DD date).
  2. It selects 3 random RAIDA servers (out of 25) and fetches the latest published client version from each using the URL: https://raida{N}.cloudcoin.global/service/qmail_client_version
  3. Responses are validated to ensure they match the YYYY-MM-DD format.
  4. A 2-of-3 consensus is required: at least 2 of the 3 responses must be identical.
  5. If consensus is reached, the remote version is compared with the local version using a simple string comparison (YYYY-MM-DD sorts lexicographically).
  6. If consensus cannot be reached (network failure, mismatched responses, invalid data), the endpoint returns success: false.

Consensus Mechanism

The same 2-of-3 RAIDA consensus pattern is used across the CloudCoin system for fetching authoritative data (server lists, user directories, wordlists, and version information). This prevents a single compromised or malfunctioning RAIDA server from returning incorrect data.

GUI Integration

The GUI should call this endpoint once at startup. Based on the response:

  • success: true + update_available: true — Prompt the user to update.
  • success: true + update_available: false — No action needed.
  • success: false — Show a non-blocking notice that the update check could not be completed. Do not prevent the user from using the application.

Related Endpoints

/api/raida/echo

Test RAIDA network connectivity and health status for all 25 servers.

View Details

/api/raida/version

Query the RAIDA server software version from each of the 25 RAIDA servers.

View Details