Services API

Overview

The Services API lets you programmatically retrieve data about the health of the IT services that you monitor with Nexthink.

The client of the Services API must trust the certificate in the primary Appliance (the Portal).

To authenticate the client, the Service API uses Basic Authentication. Nexthink recommends creating a local account to exclusively authenticate clients of the API.

Enabling the Services API

The Services API is fully tested and can be used in production. However, it is still in the phase of technical preview and you need to activate the feature before being able to use it.

To enable the Services API:

Log in to the CLI of the Portal Appliance.
Optional: If the Portal has no configuration file yet, that is, if portal.conf does not exist in folder /var/nexthink/portal/conf, create it by copying the defaults from the sample configuration file:

sudo -u nxportal cp /var/nexthink/portal/conf/portal.conf.sample \ /var/nexthink/portal/conf/portal.conf

3. Edit the Portal configuration file:

sudo vi /var/nexthink/portal/conf/portal.conf

4. Add the following line:

globalconfig.feature.service-test-api = true

5. Save your changes and exit:

:wq

6. Restart the Portal to apply your settings:

sudo systemctl restart nxportal

Finding out available service data

To interactively look for service data that is available through the Services API:

Navigate with a web browser to the following address:
```
https://<Portal_DNS_FQDN>/api/beta/services
```
- Substitute for the actual name of the Portal.
Log in to the discovery tool of the Services API:
- Type in the user credentials whenever asked by the web browser.
- The discovery tool displays the service data limited to the view domain of the user in the hierarchy.

Querying the API

To query the Services API, send a GET request to the API URL with the following parameters:

Parameter	Description	Default value
service (named metric in the request)	UID of the desired service	(none)
scope	hour (last 60 minutes) day (last 24 hours)	hour
hierarchy	Name of a hierarchy	The name of the first hierarchy in the Portal
hierarchy-level	Name of a level in the hierarchy	(none)
path	Name of a node in the hierarchy to limit the output. Chain several path elements to limit the output further down in the hierarchy levels.	The highest node in the view domain of the user
format	Output format, one of: table (for an HTML table) json csv	table

Parameter

Description

Default value

service (named metric in the request)

UID of the desired service

(none)

scope

hour (last 60 minutes)
day (last 24 hours)

hour

hierarchy

Name of a hierarchy

The name of the first hierarchy in the Portal

hierarchy-level

Name of a level in the hierarchy

(none)

path

Name of a node in the hierarchy to limit the output. Chain several path elements to limit the output further down in the hierarchy levels.

The highest node in the view domain of the user

format

Output format, one of:

table (for an HTML table)
json
csv

table

Include either the hierarchy-level or the path parameter in a Services API query, but not both simultaneously.

Example of a query URL:

https://<Portal_DNS_FQDN>/api/beta/service/data/overview?
metric=57dc824c-3507-434a-9658-2d98255c1eff&
hierarchy=Location&
path=Europe&path=Switzerland&
format=table

The Services API uses Basic Authentication. To test the API from a Nexthink appliance, you can use curl, for instance:

curl https://<Portal_DNS_FQDN>/api/beta/service/data/overview?... -u username:password

Output of the Services API

The data that you can retrieve from the Services API is similar to what you get when analyzing the health of a service from the corresponding dashboards in the Portal.

Find below the complete list of outputs of the Services API:

Output data	Description
Name of service	The name of the selected service
Names of hierarchy levels and nodes	For a hierarchy-level query, the response returns service data decomposed into all the nodes at the specified level and includes an aggregate result named all for each node at the parent level (which is the global level for levels defined at the top of the hierarchy). For a path query, the response includes service data for the node specified (grouped on the entry named all) and its immediate children; except for nodes at the Entity level, which are at the base level of the hierarchy and do not have children.
Service metrics	The service metrics depend on the service being connection-based or web-based and are the same that you can find on the service dashboards.

Output data

Description

Name of service

The name of the selected service

Names of hierarchy levels and nodes

For a hierarchy-level query, the response returns service data decomposed into all the nodes at the specified level and includes an aggregate result named all for each node at the parent level (which is the global level for levels defined at the top of the hierarchy).
For a path query, the response includes service data for the node specified (grouped on the entry named all) and its immediate children; except for nodes at the Entity level, which are at the base level of the hierarchy and do not have children.

Service metrics

The service metrics depend on the service being connection-based or web-based and are the same that you can find on the service dashboards.

RELATED TASKS

RELATED CONCEPT

Service

Last updated 4 months ago