Node API Check

Any syntax in <> brackets is a user’s unique variable/version. Exchange with a corresponding name without the <> brackets.

Operating a nym-node is not a “set and forget” endeavor, it takes some work. To diagnose node performance querying APIs is a good knowledge to have. There are two main places to look for API endpoints regarding nym-node:

• openapi.json: a list of all endpoints
• Swagger UI page

Besides that, Gateway operators can check out their node performance, connectivity and much more on harbourmaster.nymtech.net.

Basic API usage

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

# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
# for http
http://<NODE_IP_ADDRESS>:8080/api/v1/swagger/#/
# or
http://<NODE_IP_ADDRESS>/api/v1/swagger/#/

# for reversed proxy/WSS
https://<NODE_DOMAIN>/api/v1/swagger/#/

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

# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
# for http
http://<NODE_IP_ADDRESS>:8080/api/v1/roles
# or
http://<NODE_IP_ADDRESS>/api/v1/roles

# for reversed proxy/WSS
https://<NODE_DOMAIN>/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, 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 has a function counting all existing nodes in provided version.

Setup

Pre-requsities

Python3

1. Start with installing Python3:

sudo apt install python3

2. Make sure Python3 is your default Python version:

update-alternatives --install  /usr/bin/python python /usr/bin/python3 1

# controll
python --version

# should return higher than 3

3. Install Python modules tabulate, pandas and argparse:

• either using pip and then running:

pip install tabulate pandas argparse

• or if you installed Python3 system-wide you can install modules directly:

sudo apt install python3-tabulate python3-pandas python3-argparse

Installation

4. Get node_api_check.py and api_endpoints.json. If you compiled from source, you already have both of these files. 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

5. Make executable:

chmod u+x node_api_check.py

Now you are ready to check your node.

Usage

Run with --help flag to see the available commands:

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)

optional arguments:
  -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 a command, add a --help flag after the command of your choice, like in this example:

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

optional arguments:
  -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

version_count

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