Web API/Rest API

Introduction

The NetXMS Web API provides a REST-like interface for integrating external systems with the NetXMS server. API calls use JSON for data exchange. Two implementations are available:

  • Built-in Web API — embedded directly into the NetXMS server process. This is the recommended API for new integrations, however it’s still work in progress and some endpoints might not yet be available. The API is documented using an OpenAPI specification.

  • Legacy Web API — a standalone Java web application (.war file) deployed to a separate web server. This implementation will be deprecated in the future. The API is documented using an OpenAPI specification (legacy).

Information about Grafana configuration can be found here.

Built-in Web API

The built-in Web API is integrated directly into the NetXMS server process as a loadable module.

Setup

To enable the built-in Web API, add the following line to the server configuration file (netxmsd.conf):

Module = webapi

The API listens on the loopback address on port 8000 by default. Once enabled, it can be accessed at http://127.0.0.1:8000/.

Configuration

All configuration parameters are placed in the [WEBAPI] section of the server configuration file (netxmsd.conf).

Parameter

Default

Description

Enable

true

Set to false to disable the Web API without removing the module.

Address

loopback

Listener address. Empty value or loopback/localhost binds to the loopback interface only. Use any or * to listen on all interfaces. A specific IP address can also be provided.

Port

8000

HTTP listener port.

Example configuration:

Module = webapi

[WEBAPI]
Address = any
Port = 8000

TLS Configuration

The built-in Web API does not terminate TLS directly. Instead, it uses reproxy as a TLS termination proxy, which is started and managed automatically by the server when TLS is enabled. Alternatively, any external reverse proxy (e.g. Nginx) can be used for TLS termination instead of reproxy — in that case leave TLS disabled in the NetXMS configuration and configure the proxy to forward HTTPS traffic to the HTTP listener port.

Parameter

Default

Description

TLSEnable

false

Set to true to enable TLS termination using reproxy.

TLSPort

8443

HTTPS listener port (reproxy listens on this port).

TLSAddress

0.0.0.0

Address reproxy binds to for HTTPS.

TLSCertificate

(none)

Path to the TLS certificate file. Required when TLS is enabled.

TLSCertificateKey

(none)

Path to the TLS certificate private key file. Required when TLS is enabled.

ReproxyPath

/usr/bin/reproxy

Path to the reproxy executable. On Windows, defaults to reproxy.exe in the NetXMS bin directory.

Example TLS configuration:

[WEBAPI]
Address = loopback
Port = 8000
TLSEnable = true
TLSPort = 8443
TLSAddress = 0.0.0.0
TLSCertificate = /etc/ssl/certs/netxms.crt
TLSCertificateKey = /etc/ssl/private/netxms.key

Note

When TLS is enabled, it is recommended to keep the HTTP listener bound to the loopback address (default) so that unencrypted traffic is not exposed on the network.

Legacy Web API (WAR file)

Requirements

  • A running instance of the NetXMS server.

  • Access to a web server capable of deploying Java web applications (e.g. Apache Tomcat).

Setup

  1. Download netxms-websvc-VERSION.war (example: netxms-websvc-6.0.2.war) from http://www.netxms.org/download.

  2. Copy the downloaded .war file to your web server’s deployment directory.

By default, the localhost address is used to connect to the NetXMS server. To specify the server address or other parameters, create a nxapisrv.properties file and place it in the property file location of your web server. The file uses INI format (NAME=VALUE). The following parameters are supported:

Parameter

Description

netxms.server.address

NetXMS server address

netxms.server.port

NetXMS server port

netxms.server.enableCompression

Enable protocol compression

session.timeout

Session timeout

Configuration example:

netxms.server.address=server.office.example.com
netxms.server.port=44701