REST API Support

Although Nstream encourages using end-to-end streaming wherever possible, each Web Agent that is built with the Nstream Toolkit exposes the ability to receive a snapshot of its present state over a REST API.

Nstream Library Dependencies

Dependencies

Gradle

implementation 'io.nstream:nstream-adapter-common:4.12.20'

Maven

<dependency>
  <groupId>io.nstream</groupId>
  <artifactId>nstream-adapter-common</artifactId>
  <version>4.12.20</version>
  <type>module</type> <!-- Remove or comment this line for non-modular projects -->
</dependency>

The REST API support is implemented in the nstream.adapter.common.NstreamAgent class in the nstream-adapter-common module. Thus, this functionality is avaiable to all classes that extend the NstreamAgent class which include:

• Patches from the Nstream libraries
• Connector-type agents from the Nstream libraries, both ingress- and egress-type
• Any custom classes that extend the NstreamAgent

Usage

Simply issue GET-type REST requests in the following format:

(mandatory)
endpoint: $HOST_URI/$NODE_URI?lane=api/laneSummary
(optional headers)
Accept

For example, a sample cURL request to receive the data in JSON format for /agent/1 running on some-host.com:9001 could look like:

curl -XGET -H 'Accept: application/json' 'your-host.com/agent/1?lane=api/laneSummary'

The response, which:

• Is formatted as key-value pairs keyed by lane name
• Reports MapLane data inside an additional level of indirection

might look like:

{
  "shared": {
    "s1": 1
  },
  "info": {
    "a": 1,
    "b": "2"
  },
  "map": {
    "data": [
      {
        "key": "k1",
        "value": "v1"
      },
      {
        "key": "k2",
        "value": "v2"
      }
    ]
  }
}

If /agent/1 consists of multiple traits, then all of the relevant lanes for all such traits within /agent/1 will be included in the summary paylod.

Limitations

• Only MapLanes and ValueLanes are currently supported. CommandLanes do not retain state and will thus never be supported. Other lane types may be supported in the future.
• Only Recon, JSON, and plaintext Accept headers are currently considered.