As you may or may not already know, NetBeez has recently released the BeezKeeper API (RESTful). This initial version of the API provides read-only access to all the data which are accessible through NetBeez dashboard visualizations. From agents’ statuses and targets’ statuses to test statistics and alerts.
I’m taking this opportunity to go through some of the endpoints which provide the data you see on the dashboard. You can then put your creativity and interoperability skills to work and either create your own dashboards that server your very specific needs, or you can integrate your Beez data with your goto tools.
Agents
Names and IDs
In order to access agent information, you’ll first have to know their IDs. To get the agent IDs with their respective names you can use the /agent/names.json endpoint.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/agents/names.json'
List Data
The data related to getting the information rendered in the list and thumbnail views are here using the /agents/:id.json. The returned object includes all the network interfaces and their configuration as well as the IDs of tests running on the agent, IDs of targets associated with agent and groups the agent belongs to.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/agents/10.json'
Agent Test Table
Using the test IDs returned by the previous call you can get the summaries of all the tests associated with an agent by listing them as a parameter to the /nb_tests/summaries.json endpoint. You’ll have to add all the IDs at the end as ids%5B%5D=12572&ids%5B%5D=12573
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_tests/summaries.json?ids%5B%5D=12572'
Targets
Names and IDs
Similarly to the agents, in order to access target information, you’ll first have to know their IDs. To get the target IDs with their respective names you can use the /nb_targets/names.json endpoint.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_targets/names.json'
Target details
To get all the target information, such as the tests configured on a target you’ll have to use the /nb_targets/:id.json endpoint.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_targets/37.json'
In the resulting object you’ll get all the tests configured and running grouped by what we call the test template.
Test template aggregate plots
There are three components in this view:
Section 1. Aggregate performance for a specific test template: in order to retrieve this data you’ll have to use the /nb_test_statistics.json endpoint and input the right parameters to get the aggregate performance for the test template you want. The IDs of the test templates in a target can be retrieved from the previous endpoint (target details).
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_test_statistics.json?nb_test_template_id=101&window_size=1&metric_type=mean&to=1482269100000&from=1482265440000&sort=asc'
Section 2. Open alerts timeline for a test template: in order to retrieve this data you’ll have to use the /nb_alerts/open_alerts_at_intervals.json endpoint and input the right parameters to get the timeline of open alerts for the test template you want.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_alerts/open_alerts_at_intervals.json?nb_test_template_id=99&from=1482268080000&to=1482271679999&window_size=1'
Section 3. Agent performance distribution at a specific time for a test template: in order to retrieve this data you’ll have to use the /nb_test_statistics.json endpoint. This time adding the grouping=nb_test_id parameter to get the average performance of the time interval specified by from and to, by test. Since each agent runs exactly one test from the test template then you get a per agent view of this aggregate.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_test_statistics.json?nb_test_template_id=99&window_size=1&metric_type=mean&to=1482270000000&from=1482269940000&grouping=nb_test_id'
Alerts table
The data from the alerts table comes from two endpoints. One for the counts and one for the paginated alerts.
1. To get the counts for a specified period (i.e. 15 minutes, 1 hour, 4 hours, etc. as a pair of from and to timestamps) you’ll have to use the /nb_alerts/count.json and set the severity of the alerts you want. As a reference for the severity level, use the table from here: https://en.wikipedia.org/wiki/Syslog#Severity_level.
Example;
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_alerts/count.json?nb_test_template_id=99&from=1482185322260&to=1482271722260&severity_from=1&severity_to=5'
2. To get the alerts for a specified period (i.e. 15 minutes, 1 hour, 4 hours, etc. as a pair of from and to timestamps) you’ll have to use the /nb_alerts.json.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/nb_alerts.json?nb_test_template_id=99&page=0&limit=10&from=1482185322256&to=1482271722256'
Scheduled Tests
Lists
In order to retrieve the scheduled test details you’ll first have to retrieve the IDs of all the existing tests using the /scheduled_nb_test_templates/ids.json endpoint. Once you have the IDs you can then go ahead and get the details of each scheduled test using the /scheduled_nb_test_templates/:id.json endpoint.
Examples:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/scheduled_nb_test_templates/ids.json'
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/scheduled_nb_test_templates/2.json'
Scheduled test results aggregate
This view is an aggregate of the results reported by all the agents at the scheduled times. To access this data you’ll have to use the /scheduled_nb_test_results.json endpoint with the right scheduled_nb_test_template_id as a parameter.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/scheduled_nb_test_results.json?scheduled_nb_test_template_id=1&limit=14'
Scheduled test result breakdown by agent
When you click on a specific timestamp on the aggregate scheduled test view, you get a breakdown of the results per agent. In order to get this data through the API you’ll have to use the /scheduled_nb_test_results.json endpoint but this time you should use the specific timestamp of the scheduled test run.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/scheduled_nb_test_results.json?scheduled_nb_test_template_id=1×tamp=1482252600000'
Scheduled test results timeline of an agent
In this case the same endpoint is used but this time we add the agent_id as a parameter, as well as a time-range for the timeline.
Example:
curl -X GET --header 'Accept: application/json' --header 'Authorization: XXX_API_KEY_XXX' --header 'API-VERSION: v1' 'https://YOUR_NETBEEZ_INSTANCE/scheduled_nb_test_results.json?scheduled_nb_test_template_id=1&agent_id=61&from=1481056787000&to=1482252600000'
In this post, I’ve only covered a subset of the endpoints used in the dashboard but they are definitely the most important ones. I’d be happy to continue this conversation in the comments sections once you get the chance to play with your own data. A convenience API UI interface is included on your instance at https://<YOUR_NETBEEZ_INSTANCE>/swagger/index.html. I would be very interested to hear what are your use-cases for the API and how we could improve our endpoints to server those use-cases.
If you don’t have a NetBeez BeezKeeper installation yet, then head over to our website and request a demo now!
