--- title: "REST API" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/rest-api/index.html" --- ## 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 and currently 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-memory-protection-settings/index.html). For more information on the API endpoints, see the [Netprobe REST API](https://docs.itrsgroup.com/docs/geneos/5.14.0/api/rest-api/?v=/v1/rest-api.yaml). ## 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 Geneos Compatibility Matrix](https://docs.itrsgroup.com/docs/all/geneos/7x-geneos-compat-matrix/index.html#java-support). - 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html). 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html) 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](/netprobe/../../../administration/licence-daemon/). ## Setup and configuration 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-hub/data-schema-ug/index.html#create-a-data-schema). ### 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** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/save16x16.png "icon") 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** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/save16x16.png "icon") 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, REST API samplers listen on HTTP port `7136`. The default HTTPS port is `7137`, but HTTPS is only enabled if a secure port is configured and the Netprobe is started in secure mode. To configure the listening ports: 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. **Note** If you enable a secure port (HTTPS), you must also start the Netprobe with: - `-secure` - `-ssl-certificate ` - `-ssl-certificate-key ` - `-ssl-certificate-chain ` (optional but recommended) For more information, see [Netprobe Command-line Options](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-command-line-options/index.html#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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gateway_probes/index.html#probes--probe--restapihttpport) and [probes > probe > restApiHttpsPort in Probes](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gateway_probes/index.html#probes--probe--restapihttpsport). To configure the REST API plugin with mTLS authentication, refer to [Plugin configuration](#plugin-configuration). ## Dataviews ### 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: ![Sampling in dataviews](https://docscdn.itrsgroup.com/geneos/images/plug-ins/rest-api-tr-streams-sampling-status.png) 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. ![Streams Dataview](https://docscdn.itrsgroup.com/geneos/images/plug-ins/rest-api-tr-streams-dataview.png)
Headline name Description
samplingStatus Status of the sampler.
totalStreams Number of streams that have been created on the sampler.
Column name Description
name Name of the stream.
currentBufferSize

Number of messages that the sampler holds in the stream.

The sampler holds these messages until they are consumed by another sampler.
maxBufferSize

Maximum number of messages that the sampler can hold before it starts to drop earlier messages.

This field is set by the Buffer size configuration. For more information, see Plug-in configuration.
totalMessagesReceived

Total number of messages that the samplers has received in the stream.

Every request counts as a message.
totalMessagesLost Total number of messages that the sampler has dropped because the buffer was full.
**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 about API endpoints, see the [Netprobe REST API](https://docs.itrsgroup.com/docs/geneos/5.14.0/api/rest-api/?v=/v1/rest-api.yaml). For examples on what the dataviews could look like based on the HTTP body, see [Examples](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/rest-api/index.html#examples). Each custom dataview includes the following headlines: | Headline name | Description | |-------|-------| | samplingStatus | Status of the sampler. | | totalRows | Total number of rows currently in the dataview. | You can use these headlines as XPath targets to create rules for your monitoring setup. ## Plugin configuration ![REST API plugin configuration window](https://docscdn.itrsgroup.com/geneos/images/plug-ins/rest-api-config-window-7-9.png) **Note** You can safely update the configuration of this plug-in without causing the Netprobe to restart. However, any changes to the REST API SSL/mTLS settings require a Netprobe restart to take effect. | Field | Description | |-------|-------| | Buffer size | This field applies to streams. This field sets the maximum number of messages that the REST API sampler holds in memory at a time. Messages clear the buffer when the stream is consumed by another sampler, such as an FKM sampler. Default value: `1000` | | Row limit | Limits the dataview to the number of rows specified. Default value: `200` **Note** You can override this setting with a Gateway-wide row limit that you can [configure in the Gateway Setup Editor](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gateway_operating_environment/index.html#operatingenvironment--customdataviewmaxrows) under **Operating environment** > **Custom dataview max rows**. | | Verify client certificate | If enabled, the REST API will require clients to present a valid certificate. Specify the trusted CA path in **Client CA certificate**. **Note** The REST API plugin will automatically use the Netprobe `-ssl-certificate-chain` file if the **Client CA certificate** is empty and disabled. A warning is logged when this happens. Mandatory: No Default: false | | Client CA certificate | Path to the Certificate Authority (CA) certificate file used by the server. **Error** The GSE will report an error if the **Client CA certificate** is enabled and no path is specified. Mandatory: No| If you want to configure the HTTP and HTTPS ports on which the REST API samplers listen, refer to [Configure the listening port on the probe](#configure-the-listening-port-on-the-probe). ## Examples This section provides example requests and their resulting dataviews or streams. For more information on the API endpoints, see the [Netprobe REST API](https://docs.itrsgroup.com/docs/geneos/5.14.0/api/rest-api/?v=/v1/rest-api.yaml). ### 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" } ] ``` #### Example request `PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView` #### Resulting dataview
column1 column2 column3
dataA1 dataA2 dataA3
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
### Delete a dataview Consider an existing dataview called `simpleView`:
column1 column2 column3
dataA1 dataA2 dataA3
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
#### Example request `DELETE http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView` #### Resulting dataview The dataview is deleted and no longer appears in the Active Console. ### Create a row Consider an existing dataview called `simpleView`:
column1 column2 column3
dataA1 dataA2 dataA3
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
Then, consider the following JSON data specified in the HTTP body: ``` { "column1": "dataD1", "column2": "dataD2", "column3": "dataD3" } ``` #### Example request `PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataD1` #### Resulting dataview
column1 column2 column3
dataA1 dataA2 dataA3
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
dataD1 dataD2 dataD3
### Update a row Consider an existing dataview called `simpleView`:
column1 column2 column3
dataA1 dataA2 dataA3
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
Then, consider the following JSON data specified in the HTTP body: ``` { "column1": "dataA1", "column2": "dataA4", "column3": "dataA5" } ``` #### Example request `PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataA1` #### Resulting dataview
column1 column2 column3
dataA1 dataA4 dataA5
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
**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 Consider an existing dataview called `simpleView`:
column1 column2 column3
dataA1 dataA2 dataA3
dataB1 dataB2 dataB3
dataC1 dataC2 dataC3
#### Example request `DELETE http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataB1` #### Resulting dataview
column1 column2 column3
dataA1 dataA4 dataA5
dataC1 dataC2 dataC3
### 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`:
column1 column2 column3
dataA1_duplicate1 dataA21 dataA31
dataA1_duplicate2 dataA22 dataA32
dataA1_duplicate3 dataA23 dataA33
#### Example request `DELETE http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api/dataview/simpleView/row/dataA1` #### Resulting dataview Note the duplicate row numbers assigned to the remaining rows.
column1 column2 column3
dataA1_duplicate1 dataA22 dataA32
dataA1_duplicate2 dataA23 dataA33
### Create or update a stream #### Example request — sampler with type `PUT http://localhost:7136/v1/managedEntity/rest-api-me/sampler/rest-api(typeA)/stream/fkmStream` #### Resulting stream 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.