The Need for APIs
When we start thinking about APIs and how to use them, the first thing that comes to mind is always integrations and the second thing is custom dashboards – at least to me (leave a comment if that’s not the case for you).
Integrations are implemented for a variety of use-cases, e.g. configuration automation, where you integrate with other systems to perform configuration tasks on the state of your BeezKeeper server, such as renaming agents, creating new targets and tests, adding agents to groups etc. Another use-case for integrations is for automating network configuration tasks, by providing NetBeez data to a network automation system, or an SD-WAN controller. The final integration use-case I’d like to mention is to include NetBeez data into data aggregation systems, which consolidate data from multiple data sources and provide their users with analytics regarding all aspects of their operations.
APIs in NetBeez
The evolution of APIs at NetBeez started with version V0, which was the original internal dashboard and backend APIs. After a while, we released V1 of the API which includes all data retrieval endpoints for all of the data stored in NetBeez. These two APIs are not following any standards in terms of the data format other than the fact that they return JSON objects.
Last year, we started re-implementing our API in JSON API format. We will soon be phasing out our V0 and V1 APIs in favor of this one, completed by the end of 2022. This API is also used by our internal processes and dashboard. That’s why I’ll be showcasing how different dashboard components are mapped to API endpoints.
Agent Details API
Using the Agents index route you can filter and lookup agents based on their name, time they were last active, number of alerts open at the moment, etc. The information returned includes the Agent’s status, ISP name and ASN, IP addresses and other network configurations, etc.
The API endpoint is as follows:
And it returns this JSON API formatted object:
Agent Metrics API
There are 2 endpoints serving metrics directly related to the agents. Which includes the agent’s availability as well as the endpoint’s performance metrics such as RAM, CPU and Hard Drive utilization:
The agent’s availability statistics endpoint (available in V1 at the moment):
Which returns:
And for the agent performance metrics we have this endpoint:
Which returns an array of timestamped values:
Test Results & Statistics API
Test results and statistics are displayed on the Real-time graphs and historical charts, as well as on the Path Analysis graphs for correlation. They are also used on the Target details which we’ll cover next. Here’s what the Real-time graph looks like:
To get the raw results you can use this endpoint (currently in V1 but will be available in JSON API with release 10.2):
Which returns an array of timestamped raw results:
To get the test’s statistics such as mean, packet loss (timeout/error rate), jitter and MOS you can use this endpoint (currently in V1):
Which returns arrays like these ones:
Aggregate data per Target API
On the Target details view, when you open a test within a resource, it shows you 2 timeline graphs that depict the average response time over all the agents and one that depicts the number of open alerts on this specific test as a sum of what all the agents are reporting:
For the top graph, we use the same API as we do for the test statistics, but in this case we group the results by the Test Template ID:
For the second graph we use the open alerts at intervals endpoint (only available on V1):
Which returns the number of alerts open at the time, by the alert severity(1: critical, 4: warning):
Agent Alert Aggregates API
On the first page loaded when you open the dashboard, called Buzz Tab, we display a scatterplot of the number of alerts triggered by agents in the past 24 hours:
The data used to populate this scatterplot is available through the grouped alert counts endpoint:
Which returns the results on a per agent basis:
Putting it all together
The goal of this blog post is not to be comprehensive on the different APIs, but rather to give you an idea of what’s available. You can find more information about all the endpoints on our API’s documentation page.
Now let me demonstrate how different types of information can be put together (as one of our largest customers did) to produce a custom dashboard that is used by Helpdesk Support Engineers every day to help them understand how to better troubleshoot and find the root cause of issues affecting their remote worker agents. Find out more about how Helpdesk support engineers can troubleshoot remote worker issues directly using the NetBeez dashboard in last week’s blog post by Panos Vouzis.
Here’s how the dashboard looks, annotated by the APIs where the data are coming from:
If you want to find more examples of how the API is used you can check out our github API examples project, and for reference of all the APIs available you can visit the API documentation page.
If you have any questions about what’s possible with our API today and in the future please ask in the comments or hit us up by email. On the other hand if you would like to see a demo of the product and get a trial you can fill out this form.
