Operators
Operator Guides
Performance Monitoring & Testing
Node API Check

Node API Check

⚠️

CLI tool node_api_check.py, helping operators to collect all API values about their nodes locally, is not up to date with the API changes introduced with v2024.13-magura release version. Please treat it as unstable before we fix it.

ℹ️

Our documentation often refer to syntax annotated in <> brackets. We use this expression for variables that are unique to each user (like path, local moniker, versions etcetra). Any syntax in <> brackets needs to be substituted with your correct name or version, without the <> brackets. If you are unsure, please check our table of essential parameters and variables (opens in a new tab).

Operating a nym-node is not a "set and forget" endeavor, it takes some work. To diagnose node network performance through querying APIs, is a good knowledge to have. These are the main places to look for API endpoints regarding nym-node:

Besides that, node operators can check out their node performance, connectivity and much more on harbourmaster.nymtech.net (opens in a new tab).

Basic API usage

For information about available endpoints and their status, you can refer to:

# for http
http://<PUBLIC_IP>:8080/api/v1/swagger/#/
# or
http://<PUBLIC_IP>/api/v1/swagger/#/
 
# for reversed proxy/WSS
https://<HOSTNAME>/api/v1/swagger/#/

For example to determine which mode your node is running, you can check :8080/api/v1/roles endpoint:

# for http
http://<PUBLIC_IP>:8080/api/v1/roles
# or
http://<PUBLIC_IP>/api/v1/roles
 
# for reversed proxy/WSS
https://<HOSTNAME>/api/v1/roles

node_api_check.py

To make this a bit easier, we made a CLI tool querying all available API endpoints based on node Identity Key (further denoted as <ID_KEY>) called node_api_check.py. To diagnose your node performance, whether by yourself or by sharing an output in our operator channel (opens in a new tab), this tool provides you with a quick overview of live data. We recommend to run this checker alongside nym_gateway_probe to triage both performance and an actual routing.

Besides querying any bonded node APIs, nym_api_check.py has a function counting all existing nodes in provided version.

Setup

Pre-requsities

1. Install and configure Python3
  • Start with installing Python3:
sudo apt install python3
  • Make sure Python3 is your default Python version:
update-alternatives --install  /usr/bin/python python /usr/bin/python3 1
  • Verify:
python --version
 
# should return higher than 3
  • Install Python modules tabulate, pandas and argparse either using pip (opens in a new tab) or if you installed Python3 system-wide you can install modules directly:
2. Install node_api_check.py and make executable

To run the program you neet to have node_api_check.py (opens in a new tab) and api_endpoints.json (opens in a new tab).

  • If you compiled from source, you already have both of these files. Note that the latest version of this program may be on develop branch.

  • If you prefer to download them individually, do it by opening terminal in your desired location and running:

wget https://raw.githubusercontent.com/nymtech/nym/tree/develop/node_api_check.py
 
wget https://raw.githubusercontent.com/nymtech/nym/tree/develop/api_endpoints.json
  • Make executable:
chmod u+x node_api_check.py

Now you are ready to check your node.

Usage & Commands

  • Run the program with --help flag to see the available commands:
./node_api_check.py --help
  • Command Output:
usage: Nym-node API check [-h] [-V]
                          {query_stats,q,query,version_count,v,version} ...
 
Run through all endpoints and print results.
 
positional arguments:
  {query_stats,q,query,version_count,v,version}
    query_stats (q, query)
                        Get all nodes API endpoints
    version_count (v, version)
                        Sum of nodes in given version(s)
 
options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

query_stats

When you want to see all the options connected to any command, add a --help flag after the command of your choice. Command query_stats is the most useful one of this program.

./node_api_check query_stats --help
  • Command output:
usage: Nym-node API check query_stats [-h] [--no_routing_history]
                                      [--no_verloc_metrics] [-m] [-o [OUTPUT]]
                                      id
 
positional arguments:
  id                    supply nym-node identity key
 
options:
  -h, --help            show this help message and exit
  --no_routing_history  Display node stats without routing history
  --no_verloc_metrics   Display node stats without verloc metrics
  -m, --markdown        Display results in markdown format
  -o [OUTPUT], --output [OUTPUT]
                        Save results to file (in current dir or supply with
                        path without filename)

The most common usage may be ./node_api_check.py query_stats <ID_KEY> where <ID_KEY> is required, substitute it with node Identity Key.

Optional arguments

FlagShortcutDescription
--markdown-mreturns output in markdown format
--no_routing_historyNonereturns output without routing history which can be lengthy
--no_verloc_metricsNonereturns output without verloc measurement which can be lengthy
--output-oexports output to a file, possible to add a target path

version_count

💡

To see a quick overview of nym-node version distribution in numbers and graph, visit Nym Harbourmaster (opens in a new tab).

Another command is version_count where at least one nym-node version is required. In case of multiple version count, separate the versions with space. We recommend to run this command with --markdown flag for a nicer output. This is an example where we want to look up how many registered nodes are on versions 1.1.0, 1.1.1, 1.1.2 and 1.1.3:

./node_api_check version_count 1.1.0 1.1.1 1.1.2 1.1.3 --markdown
Gateway ProbePrometheus & Grafana