Welcome

This documentation provides technical details of the NetLD/ThirdEye integration API. Why use the API? It lets you connect netLD/ThirdEye with the other tools your team relies on and automate work that would otherwise need to be done manually. For example, you might use it to retrieve inventory and telemetry for a dashboard, incorporate configuration and compliance data into reports, or connect network-management tasks with your existing workflows.

JSON-RPC

The NetLD/ThirdEye server exposes a JSON-RPC 2.0 API over HTTPS for language neutral integration from external systems. There are many JSON-RPC 2.0 client libraries available for all major languages.

All requests to the API use the POST method.

The use of JSON-RPC means that the underlying data sent to or received from the server is in JSON (JavaScript Object Notation) format. All strings are encoded using UTF-8 encoding, no other encodings are supported.

Access and Authentication

Before calling the API, generate an API key in netLD/ThirdEye. Treat the key like a password: store it securely, do not put it in source code, and give it only the permissions your integration needs.

Use the API key to authenticate once and establish a server session:

1. Send a GET request to https://server/rest with the API key in the Authorization header:

   Authorization: Bearer your-api-key
   

2. Preserve the session cookie or cookies returned by the server.

3. Send subsequent JSON-RPC requests to https://server/rest using the POST method and the saved session cookies.

Do not place a username, password, or API key in the URL. Your HTTP client or JSON-RPC library should maintain the session and return its cookies with each subsequent request. Use HTTPS and verify the server certificate so credentials, cookies, and API data remain protected in transit.

The API documentation shows examples of “raw” JSON requests, but it is recommended that you use JSON-RPC libraries appropriate for your language of choice, which will handle the JSON generation for you.

Results Paging

Methods that can return many results use a pageData object. Set offset to the zero-based position where the page should begin and pageSize to the maximum number of results to return. Start with an offset of 0.

For example, this request asks for the first 10 configuration change-log entries:

{
  "jsonrpc": "2.0",
  "method": "Configuration.retrieveSnapshotChangeLog",
  "params": {
    "network": "Default",
    "ipAddress": "10.95.1.68",
    "pageData": {
      "offset": 0,
      "pageSize": 10
    }
  },
  "id": "4b7c7c20-b5f5-4ccf-abd8-c71630ab35c3"
}

When the requested offset is 0, the result includes the paging values, the total number of matching records, and a method-specific array containing the current page:

{
  "jsonrpc": "2.0",
  "id": "4b7c7c20-b5f5-4ccf-abd8-c71630ab35c3",
  "result": {
    "offset": 0,
    "pageSize": 10,
    "total": 61,
    "changeLogs": [
      {
        "changes": [{ "...": "..." }]
      }
    ]
  }
}

Keep the total value from the first response; it may not be populated on later pages. To retrieve the next page, send the same request with offset increased by pageSize—in this example, use offsets 10, 20, and so on. When offset + pageSize is greater than or equal to total, you have reached the final page. The name of the results array varies by method; here it is changeLogs.

Examples

LogicVein maintains a community repository of examples on GitHub. The NetLD-SDK repository provides basic and advanced examples of interacting with the API using Python 3, nodeJS and PowerShell.