REST API

Overview Copied

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.

Caution

Depending on the rate of incoming requests, the REST API plug-in may be resource-intensive and can cause the Netprobe to reach its memory protection ratio.

In cases where you encounter Netprobe restarts, consider increasing the memory protection ratio. For guidance, see Netprobe Memory Protection Settings.

For more information on the API endpoints, see the Netprobe REST API.

Intended audience Copied

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 Copied

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 Copied

• You must have Java installed on the machine running the Netprobe. For information on supported Java versions, see Java support in Geneos 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.

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 Copied

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 Copied

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

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

Note

If you are using this plugin with Gateway Hub, you must create a user defined data schema. For instructions, see Create a data schema.

Create the REST API sampler Copied

1. In the Gateway Setup Editor, create a new sampler by right-clicking the Samplers folder and selecting New Sampler.
2. Enter a name for this sampler. For example, enter “rest-api” in the Name field.
3. Under the Plugin field, click the drop-down list and select rest-api.
4. 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 Copied

1. In the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder and selecting New Managed entity.
2. Enter a name for this managed entity. For example, enter “rest-api-me” in the Name field.
3. In the Options field, select the probe on which you want the sampler to run.
4. Under the Sampler field, click Add new.
5. In the text field under Ref, select the sampler you just created from the drop-down list.
6. 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 Copied

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:

1. In the Gateway Setup Editor, click the probe associated with the REST API sampler.
2. 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.

Dataviews Copied

Sampling in dataviews Copied

Once the REST API sampler is running and receiving API requests, the resulting dataviews on the managed entity show the following sampling information:

Note that the sampling options are greyed out, and the status bears the message, Sampling dependent on 3rd Party Application.

Streams Dataview Copied

When you use the stream endpoint on a REST API sampler, the sampler creates a dataview to monitor the status of the stream.

The name of this dataview is Streams Dataview and is fixed. No REST API plug-in endpoint can operate on this dataview name.

Note

Stream messages are stored in the buffer until they are consumed by another component. However, If there are no samplers or clients consuming the stream, then the stream registry purges the messages immediately.

Custom dataviews Copied

Dataviews and streams from the REST API plug-in depend on the content pushed to its listening ports through API endpoints. For more information, see the Netprobe REST API.

For examples on what the dataviews could look like based on the HTTP body, see Examples.

Plugin configuration Copied

Note

You can safely update the configuration of this plug-in without causing the Netprobe to restart.

Note

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 for the REST API sampler, see probes > probe > restApiHttpPort and probes > probe > restApiHttpsPort in Probes.

Examples Copied

This section provides example requests and their resulting dataviews or streams. For more information on the API endpoints, see the Netprobe REST API.

Create or update a dataview Copied

Consider the following JSON data specified in the HTTP body:

[
  {
 "column1": "dataA1",
 "column2": "dataA2",
 "column3": "dataA3"
  },
  {
 "column1": "dataB1",
 "column2": "dataB2",
 "column3": "dataB3"
  },
  {
 "column1": "dataC1",
 "column2": "dataC2",
 "column3": "dataC3"
  }
]

Example request Copied

PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView

Resulting dataview Copied

Delete a dataview Copied

Consider an existing dataview called simpleView:

Example request Copied

DELETE http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView

Resulting dataview Copied

The dataview is deleted and no longer appears in the Active Console.

Create a row Copied

Consider an existing dataview called simpleView:

Then, consider the following JSON data specified in the HTTP body:

  {
 "column1": "dataD1",
 "column2": "dataD2",
 "column3": "dataD3"
  }

Example request Copied

PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataD1

Resulting dataview Copied

Update a row Copied

Consider an existing dataview called simpleView:

Then, consider the following JSON data specified in the HTTP body:

  {
 "column1": "dataA1",
 "column2": "dataA4",
 "column3": "dataA5"
  }

Example request Copied

PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataA1

Resulting dataview Copied

Note

When you update a row, check that you include values for all cells in that row. Any missing value is considered blank and shows up as a blank cell in the dataview.

If the HTTP body has a different value for the {rowname}, then the plug-in updates the {rowname}, as well.

Delete a row Copied

Consider an existing dataview called simpleView:

Example request Copied

DELETE http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataB1

Resulting dataview Copied

Delete a duplicate row Copied

When a dataview receives multiple rows with the same row name, Geneos treats subsequent rows as duplicates, and appends _duplicate* to the row name after the Netprobe publishes the dataview to the Gateway. The asterisk in _duplicate* increments numerically from 1.

Consider an existing dataview called simpleView:

Example request Copied

DELETE http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataA1

Resulting dataview Copied

Note the duplicate row numbers assigned to the remaining rows.

Create or update a stream Copied

Example request — sampler with type Copied

PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api(typeA)/stream/fkmStream

Resulting stream Copied

The REST API plug-in simply passes the content received to the stream, regardless of its form.

If the stream name already exists, then the sampler updates the existing stream.