API Reference

The API is constructed in a way that allows users to easily follow the hierarchy down, creating a URL that will access specific requested data.

In the example of this systems API return we see what we call nodes. Each node is a specific part of the API that gets specific data and functions a certain way. These are also sometimes referred to as API endpoints when farther down the list, when we have reached the end of a node.

Open up your web browser, and navigate to the URL below, replacing localhost:5693 with your NCPA server hostname/IP and port or if you're reading this inside NCPA, you can look at the box.

https://localhost:5693/api?token=mytoken

The API is formatted as JSON. If you're used to interacting with APIs, this shouldn't be too much of a surprise. However, something unique to NCPA is the way the API is accessed.

NCPA is structured with a set of base modules and each module has nodes. The nodes end up forming a URL, which is used to get data about that specific item or to run a check on that specific item's data.

Take a look at how an API call is formatted by hovering over each section:

https://localhost:5693/api  /  memory  /  virtual/total  ?  token=mytoken

Nodes are direct key names shown in the JSON, so essentially you are creating a way to access the endpoint by selecting which nodes to follow. The module and nodes together form the endpoint requested. In this case, the endpoint would be memory/virtual/total. The additional URL parameters after the ? are used to filter datasets, convert values or units, and authenticate using the token.

The CPU module let's you get information on the currently used system-wide percentage. You can also view the CPU's idle, user, and system time. Since most modern day systems have multiple CPU cores, there is a cpu/count endpoint that gives the amount of cores. This may be helpful when interpreting the other endpoints, since each core is reported separately.

If you'd like to see an aggregated view of the endpoints, the CPU module has a special parameter called aggregate that will aggregate all values by a specific aggregation type.

Example of CPU Usage Per Core

https://localhost:5693/api/cpu/percent?token=mytoken

{
    "percent": [
        [
            18.8, 
            0.0, 
            1.5, 
            0.0, 
            13.8, 
            0.0, 
            3.2, 
            0.0
        ], 
        "%"
    ]
}

Example of Aggregation

https://localhost:5693/api/cpu/percent?token=mytoken&aggregate=avg

{
    "percent": [
        [
            3.81
        ],
        "%"
    ]
}

Basic Parameters

The disk module is fairly large and one of the few modules to have combined check results for multiple nodes inside the disk/logical node. The disk module shows mount information, logical partition usage, and physical disk statistics through three main nodes shown below:

• disk/mount - Information on mounted devices that are not disks.
• disk/logical - Information on each mounted disk partition. Remember all \ and / must be represented as |.
• disk/physical - Each physical drive's hardware stats and information.

Example of Disk Data

https://localhost:5693/api/disk/logical/C:|?token=mytoken&units=Gi

{
    "C:|": {
        "used_percent": [
            76.8,
            "%"
        ],
        "used": [
            356.94,
            "GiB"
        ],
        "opts": "rw,fixed",
        "total_size": [
            464.87,
            "GiB"
        ],
        "fstype": "NTFS",
        "free": [
            107.93,
            "GiB"
        ],
        "device_name": [
            "C:\\"
        ]
    }
}

Basic Parameters

The interface module is a group of counters for each of the available network interfaces that exist. You can see by the example below that there is quite a lot of information. The most important part for most people is going to be the bytes_recv and bytes_sent values.

This particular node can use delta=1 to get the change in bytes send or received since the last check, making it able to produce bandwidth usage data.

Example of Interface Data

https://localhost:5693/api/interface/Local Area Connection?token=mytoken&units=Gi

{
    "Local Area Connection": {
        "packets_sent": [
            24194869,
            "packets"
        ],
        "bytes_recv": [
            20.95,
            "GiB"
        ],
        "packets_recv": [
            25115980,
            "packets"
        ],
        "bytes_sent": [
            9.87,
            "GiB"
        ],
        ...
    }
}

Example of Bytes Received/Second

This example shows the average of bytes received per second since the last check.

https://localhost:5693/api/interface/Local%20Area%20Connection/bytes_recv?token=mytoken&delta=1&units=k

{
    "bytes_recv": [
        3.56, 
        "kB/s"
    ]
}

Basic Parameters

The memory module shows the virtual and swap memory information. This module supports combined check results on both nodes. The percent used is probably the most commonly used value here and it is the primary value that is displayed in combined checks, along with the other node values.

Percent is actually percent used based on available memory (which includes free) and calculated like so: percent = total - available / 100

Example of Memory Data

https://localhost:5693/api/memory/virtual?token=mytoken&units=Gi

{
    "virtual": {
        "available": [
            19.83,
            "GiB"
        ],
        "total": [
            31.89,
            "GiB"
        ],
        "percent": [
            37.8,
            "%"
        ],
        "free": [
            19.83,
            "GiB"
        ],
        "used": [
            12.07,
            "GiB"
        ]
    }
}

Basic Parameters

Processes shows the list of currently running processes. It also includes data about the process such as the PID, memory, CPU usage, user, and binary name. You can filter the processes list to get specific processes. You can also get a combined check on processes giving the total process count. This combined check is special since you can filter the total processes that the check is looking for.

Example of Total Process Count Check

https://localhost:5693/api/processes?token=mytoken&check=1

{
    "returncode": 0, 
    "stdout": "OK: Process count was 119 | 'process_count'=119;;;"
}

Example Search for Processes Check

This example is searching for the word "steam" in all processes and reporting the amount it finds in the form of check results. This can be helpful if you need to make sure only so many processes are running.

https://localhost:5693/api/processes?token=mytoken&name=Steam&match=search&check=true

{
    "returncode": 0,
    "stdout": "OK: Process count for processes named steam was 5 | 'process_count'=5;;;"
}

Example Search for Processes Check with Multiple Names

An example that displays searching with multiple process names and how it adds them with or.

https://localhost:5693/api/processes?token=mytoken&name=steam&name=chrome&combiner=or&match=search&check=true

{
    "returncode": 0,
    "stdout": "OK: Process count for processes named steam,chrome was 15 | 'process_count'=15;;;"
}

These are pretty basic examples of how to use the processes module. You can view, in real time, the available output of processes by using the API section of the GUI.

Filter Parameters

These are special parameters that are applied to the processes module and filter out processes. You can apply as many filters as you want and multiple of each if necessary. These are combined using the combiner parameter which is and by default and not specified.

Basic Parameters

This node is different than most of the standard nodes. When using just the services endpoint you will see a list of all services NCPA can find and their current state. You can select a single service by adding the service=<servicename> parameter. You can also turn the service parameter into a search by adding the match=search parameter to the query.

Example of Service Filtering

https://localhost:5693/api/services?service=sshd&service=httpd

{
    "services": {
        "sshd": "running",
        "httpd": "stopped"
    }
}

Example of Service Check

https://localhost:5693/api/services?service=sshd&status=running&check=1

{
    "returncode": 0, 
    "stdout": "OK: Service sshd is running"
}

Filter Parameters

You can filter down the list of services during a query and during a check by defining the service names. You can also use the service parameter as a search if you set the match parameter to search or regex.

Basic Parameters

This extended module currently only works for Windows event logs. This module will not show any data by default since it does not know the name of logs to look for. Instead, you will see a short explanation on how to get data. You can start seeing logs by setting the name parameter. The name should correspond to a name of event log. Typically Windows systems have System and Application so our examples will use those.

Like other filter parameters, name can have multiple values. So name=Application&name=System would give Application and System logs.

Example of Application Logs

This will list all Application logs within the last 24 hours (the default look-back period) in a list. The list has been truncated due to the amount of logs.

https://localhost:5693/api/logs?token=mytoken&name=Application

{
    "logs": [
        {
            "Application": [
                {
                    "category": "0",
                    "severity": "INFORMATION",
                    "event_id": "0",
                    "application": "Service1",
                    "computer_name": "Win10-PC",
                    "message": "PowerEvent handled successfully by the service.\r\n",
                    "time_generated": "12/04/16 01:15:37"
                },
                ...
            ]
        },
        "logs"
    ]
}

Example Check with Multiple Types

Check results for multiple log types over the last 1 week period.

https://localhost:5693/api/logs?token=mytoken&name=System&name=Application&logged_after=1w&check=true

{
    "returncode": 0,
    "stdout": "OK: Application has 362 logs, System has 205 logs, Total Count has 567 logs (Time range - last 1 week) | 'Application'=362;;; 'System'=205;;; 'Total Count'=567;;;"
}

Filter Parameters

These parameters are what filter the logs that are returned. Each event log type (defined by name) is listed separately by the name with it's own list of logs.

Basic Parameters

This extended module gives access to Windows counters. There are multiple types of counters that are available should work. Per second counters, or counters that show data over time, must be passed a sleep value given or they will always return a 0 result.

Example of a Windows Counter

https://localhost:5693/api/windowscounters/TCPv4/Connections Active?token=mytoken

{
    "windowscounters": [
        1421,
        "Connections Active"
    ]
}

Examples of Counters Over Time

Any counter that requires data over time can be shown by adding sleep.

https://localhost:5693/api/windowscounters/Processor(_Total)/% User Time?token=mytoken&sleep=5

{
    "windowscounters": [
        6.43,
        "% User Time"
    ]
}

Per second counters also use the sleep parameter.

https://localhost:5693/api/windowscounters/TCPv4/Segments Received/sec?token=mytoken&sleep=5

{
    "windowscounters": [
        1069.79,
        "Segments Received/sec"
    ]
}

Example of Per Second Counters Using Delta

Counters that are not typically per second can use the delta parameter to show the average change over time (in seconds) since the last query.

https://localhost:5693/api/windowscounters/TCPv4/Connections Active?token=mytoken&delta=1

{
    "windowscounters": [
        3.61,
        "Connections Active/s"
    ]
}

Basic Parameters