REST API Plug-in User Guide

Overview

The REST API plug-in enables a sampler to listen to inbound messages on an HTTP or HTTPS connection. It is available beginning the GA4.12.x Netprobe.

In contrast to the REST Extractor plug-in, which queries a source URL to pull JSON content, the REST API ingests content as pushed to its listening port.

The listening ports are provided on the probe level.

The REST API plug-in can output the data into two formats:

As a dataview — accepts JSON content.
As a stream — accepts any message type, regardless of format.

These outputs are configured through REST API endpoints. These endpoints are versioned. The current version is v1.

This user guide walks you through setting up a REST API sampler. For guidance on using the REST API endpoints to create dataviews or streams, see the REST API Plug-in Technical Reference.

Intended audience

This guide is directed towards Geneos users who want to set up a plug-in to ingest data streamed into its listening port, without the need for a sampler to periodically query the source.

As a user, you should be familiar with REST API.

Prerequisites

The REST API plug-in does not require a source URL to be identified. To use the REST API plug-in, you only need the following to set up:

A source that pushes content. This could be a server running on your organisation system, or a third-party server.
Machine name or IP address of the machine where the REST API samplers run.
If using an HTTPS connection:
- SSL certificate
- SSL certificate key

Java requirements

You must have Java installed on the machine running the Netprobe. For information on supported Java versions, see Java support in 5.x Compatibility Matrix.
Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see Configure the Java environment.

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

Licence and version requirements

Usage of the REST API plug-in requires you to upgrade to the GA4.12.x Netprobe.

In addition, the Gateway must connect to the GA4.12.x Licence Daemon to validate the Gateway schema and tokens. For guidance, see Geneos Licence Daemon.

Setup and configuration

Setup for the REST API plug-in involves two main tasks and an optional task:

Create the REST API sampler.
Associate the REST API sampler with a managed entity.
(Optional) Configure the listening port on the probe.

Create the REST API sampler

In the Gateway Setup Editor, create a new sampler by right-clicking the Samplers folder and selecting New Sampler.
Enter a name for this sampler. For example, enter "rest-api" in the Name field.
Under the Plugin field, click the drop-down list and select rest-api.
Click Save current document to apply your changes.

Success: The sampler can now be associated with a managed entity.

Associate the REST API sampler with a managed entity

In the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder and selecting New Managed entity.
Enter a name for this managed entity. For example, enter "rest-api-me" in the Name field.
In the Options field, select the probe on which you want the sampler to run.
Under the Sampler field, click Add new.
In the text field under Ref, select the sampler you just created from the drop-down list.
Click Save current document to apply your changes.

Success: The REST API is now set up and is ready to ingest incoming JSON content.

Configure the listening port on the probe

By default, the REST API samplers listen on the HTTP port, with a default value of 7136.

If you wish to configure the listening ports or use an HTTPS connection:

In the Gateway Setup Editor, click the probe associated with the REST API sampler.
In the Advanced tab, specify the listening port under the following fields, as applicable:
- Rest api http port for insecure (HTTP) connections.
- Rest api https port for secure (HTTPS) connections.

If you wish to use a secure port, click the Rest api https port to enable the setting. In addition, you must set the SSL certificate and SSL certificate key in the command line. For more information, see Netprobe Command-line Options.

Note: You can configure the REST API sampler to listen on both insecure and secure ports concurrently. For more information on how the REST API sampler uses the listening ports, see probes > probe > restApiHttpPort and probes > probe > restApiHttpsPort in Probes.