REST API

Java 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.

Create the REST API sampler

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

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

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.

Sampling in dataviews

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

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

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.

Create or update a dataview

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"
  }
]					

Delete a dataview

Consider an existing dataview called simpleView:

Create a row

Consider an existing dataview called simpleView:

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

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

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

Delete a row

Consider an existing dataview called simpleView:

Delete a duplicate row

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:

Create or update a stream