REST API: Usage

Document created by RSA Information Design and Development on Apr 10, 2019
Version 1Show Document
  • View in full screen mode
 

The REST API accepts commands by using URL parameters and by POSTing application/json.

The special content type, application/x-netwitness-string-params, passes parameters, as plain text, in the format:

param1=value1 param2="value \"2\""

Note: Quotes, as part of the value, must be preceded by the backslash \ character. Any character can be escaped in this manner, including the backslash itself \\.

The format of the URL consists of the following components:

http://<hostname or IP>:<port>/[node1][/node2][…]?msg=<message name>[&param1=value1][&param2=value2][…]

Usage example: the "/logs" Node

The /logs node supports several different messages:

  • ls–Returns a list of child nodes. It supports the parameters depth and options.
  • mon–Monitor this node (and possibly descendants) for changes. However, this message is not supported by the REST API because it requires a persistent connection and pipe that cannot be done via REST. Monitoring currently requires the full NextGen SDK library.
  • pull–This command pulls logs from the service. It supports two parameters: count, which controls how many logs to return, and id2, which controls the ending log ID to return. id2 is optional and when it is not provided, the last log written is returned.
  • info–Returns detailed node information.
  • help–The parameters are covered in more detail in Find More Details.
  • count–A simple command to return the number of child nodes.
  • stopMon–Stop monitoring the node from a previous mon command (also not supported by REST).
  • download–A more complicated command to download a large number of log messages with several parameters to control log types and text matching capabilities. Like the mon command, this requires more than a simple request/response, which is not supported by the REST node interface.
  • timeroll–Any log entries that exceed a given age are deleted.

To get a full list of NEXTGEN messages and parameters, use the help message:

http://<hostname>:<port>/logs?msg=help

The above command returns:

Example Syntax

To view the last 100 logs:

http://hostname:50105/logs?msg=pull

To view the logs in XML format:

http://hostname:50105/logs?msg=pull&force-content-type=text/xml

To see the last 10 logs in plain text:

http://hostname:50105/logs?msg=pull&count=10&force-content-type=text/plain

Find More Details

For more detailed information about a message (for example the pull message), request help specific to just that message. The help message displayed above uses the parameter name msg, but in the URL below, message is used, an alias for the help msg parameter to avoid conflicts with the REST API msg.

http://<hostname>:<port>/logs?msg=help&message=pull

Alternately, you can go back to the browser and click the (*) in the properties pane on one of the nodes, as shown here:

When you select a command, the Message Help is displayed. When you click Send, the output is shown in a separate pane, as shown here:

In this view, you can easily navigate the node tree to use the various commands supported by NEXTGEN or to make configuration changes.

For example, from /sys/config, you can make configuration changes and click Set to send the changes.

Previous Topic:Intro
Next Topic:Enable
You are here
Table of Contents > Usage

Attachments

    Outcomes