Using the REST API
Netshot exposes most of its features to third-party or own-made scripts via a REST API.
The Web User Interface totally relies on the REST API to communicate with the server. This means that any feature available in the Web interface has a corresponding endpoint within the REST API.
The REST API supports both XML and JSON encoding.
Starting with Netshot 0.16, the OpenAPI definition of Netshot REST API is accessible on any Netshot deployment at https://[server:port]/api/openapi.json.
A GUI to explore and test the API can be accessed on https://[server:port]/api-browser/ or by clicking API Browser in the Help menu.
The list of endpoints can be retrieved from a running Netshot server via https://[server:port]/api/application.wadl.
Starting with Netshot 0.16, API tokens can be generated from the Admin page. The token must be copied immediately as it cannot be retrieved once stored.
To use the token, pass it as X-Netshot-API-Token header in the requests -- this obsoletes session-based (Cookie-based) user authentication for REST calls from scripts.
This is the legacy method. Call (POST) /api/user with username and password to get a JESSSIONID cookie value, which can be later passed along next calls. Call (DELETE) api/user to logout.
Example with cUrl:
$ curl -v -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{ "username": "script", "password": "automation" }' https://[server:port]/api/user
Note down the authentication cookie (NetshotSessionID=[the ID]), then use it in subsequent calls:
$ curl -v -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Cookie: NetshotSessionID=[the ID]" -d '...' https://[server:port]/api/...
$ curl -v -X DELETE -H "Accept: application/json" -H "Cookie: NetshotSessionID=[the ID]" https://[server:port]/api/user/0
Note: Use JSESSIONID in Netshot < 0.20
Here is a very quick example on how to start a scanning task. Let's use cURL to pass the REST commands, from the Linux command line -- in real life the same REST commands would probably be initiated from a Python or Perl script. We're going to ask Netshot to scan the subnet 10.16.16.0/24 in order to discover network devices. That's the programmatic equivalent to the Scan subnet(s) for devices option in the Add device... menu within the Netshot web UI.
Ensure you have generated a token for the API (Admin page, API Tokens section, click Add).
Schedule the scan task, to run immediately:
$ curl -v -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "X-Netshot-API-Token: [Token just generated]" -d '{ "type": "ScanSubnetsTask", "domain": "1", "subnets": "10.16.16.0/24" }' https://${netshotserver}/api/tasks
Netshot should start scanning the devices in the provided subnet, using the SNMP credentials it knows about. Any new device will be added to the DB and further discovered (configuration snapshot, compliance check, etc.).
While browsing the Netshot Web UI, open the Developper Tools (F12) of Chrome or Firefox, and switch to the Network tab to display the list of REST calls.