REST API Plug-in Technical Reference
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 technical reference contains detailed examples of REST API requests, its resulting dataviews or streams, as well as its configuration options. If you are looking to set up REST API samplers on your Netprobe, see REST API Plug-in User Guide. For more information on its available endpoints, see the Netprobe REST API.
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.
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.
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:
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.
| 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, see the Netprobe REST API.
For examples on what the dataviews could look like based on the HTTP body, see Examples.
Plug-in configuration
Caution: When you update the configuration of certain Java-based plug-ins, including this one, the Netprobe running it has to restart. Be aware of other potentially unrelated plug-ins that can be affected when you configure this particular plug-in.
| 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: |
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
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
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.
Further reading
If you are interested in setting up the REST API plug-in for your organisation, see the REST API Plug-in User Guide.
For more information on the endpoints available to the REST API plug-in, see the Netprobe REST API.