60
edits
REST API description: Difference between revisions
no edit summary
No edit summary |
|||
| Line 1: | Line 1: | ||
This page describes how to access and use the REST API. It allows to post-process data with 3rd party systems. The Allegro web interface is itself based on this REST API and all displayed statistics can be extracted from the Allegro with this API. | This page describes how to access and use the REST API. It allows to post-process data with 3rd party systems. The Allegro Network Multimeter web interface is itself based on this REST API and all displayed statistics can be extracted from the Allegro Network Multimeter with this API. | ||
== General API Setup == | == General API Setup == | ||
| Line 17: | Line 17: | ||
The credentials are the same as for the web interface. The admin user allows to access all APIs. A non-admin user has read access to most of the statistics. If you have enabled the pcap role, the capture URL is also possible for the API. | The credentials are the same as for the web interface. The admin user allows to access all APIs. A non-admin user has read access to most of the statistics. If you have enabled the pcap role, the capture URL is also possible for the API. | ||
Allegro recommends to set up a separate non-admin user with or without the pcap role for the REST API of only statistics shall be gathered. This will prevent to accidentally shut down or change any configuration by calling the REST API. | Allegro Packets recommends to set up a separate non-admin user with or without the pcap role for the REST API of only statistics shall be gathered. This will prevent to accidentally shut down or change any configuration by calling the REST API. | ||
== Useful shell commands and their parameters == | == Useful shell commands and their parameters == | ||
| Line 69: | Line 69: | ||
=== Query available URIs with OPTIONS === | === Query available URIs with OPTIONS === | ||
The Allegro REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl. | The Allegro Network Multimeter REST API has the fixed URI <code>API/stats</code> for statistics. To see all possible subtrees of a specific request, use the '''OPTIONS''' request instead of '''GET'''. It can be set with the parameter <code>-X OPTIONS</code> for curl. | ||
<pre> | <pre> | ||
| Line 90: | Line 90: | ||
</pre> | </pre> | ||
This allows you to query for example for all modules that are available for a specific release of the Allegro: | This allows you to query for example for all modules that are available for a specific release of the Allegro Network Multimeter: | ||
<pre> | <pre> | ||
| Line 172: | Line 172: | ||
== JSON output traffic counters == | == JSON output traffic counters == | ||
All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows: | All counters are aggregated counters, either for the selected time interval or since the processing start of the Allegro Network Multimeter. Many traffic counters have 4 separate values. These traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows: | ||
* line 1: '''received packets''', extraction example: jq .lastSecond[0] | * line 1: '''received packets''', extraction example: jq .lastSecond[0] | ||
* line 2: '''received bytes''', extraction example: jq .lastSecond[1] | * line 2: '''received bytes''', extraction example: jq .lastSecond[1] | ||
| Line 197: | Line 197: | ||
== API parameters == | == API parameters == | ||
The Allegro REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit. | The Allegro Network Multimeter REST API has a number of query parameters that can be added to modify the request. By default, the API will display the real time counters since the last restart of the processing unit. | ||
This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together. | This example extracts the amount of received and transmitted bytes for an IP address since the processing start of the Allegro Network Multimeter. It queries via the REST API the JSON and then adds the values second value ( row 1, rx bytes ) and 4th value ( row 3, tx bytes ) of the interval counters together. | ||
<pre> | <pre> | ||
| Line 223: | Line 223: | ||
* sort: Sorting criteria for the list. Following criteria's are supported for most lists: | * sort: Sorting criteria for the list. Following criteria's are supported for most lists: | ||
** bytes: Received and transmitted bytes (either in selected time interval or since start of the Multimeter). | ** bytes: Received and transmitted bytes (either in selected time interval or since start of the Allegro Network Multimeter). | ||
** rxbytes: Received bytes. | ** rxbytes: Received bytes. | ||
** txbytes: Transmitted bytes. | ** txbytes: Transmitted bytes. | ||
| Line 276: | Line 276: | ||
Pcap upload and analysis can also be done via API calls. | Pcap upload and analysis can also be done via API calls. | ||
The PCAP upload is split into 3 commands. First, the replay is being initialized. Then the analyzing is started. In the last step the PCAP is streamed to the Multimeter. Depending on the size of the PCAP the third step could take some time, but the Allegro already allows access to the statistics of the already analyzed packets via web/API. | The PCAP upload is split into 3 commands. First, the replay is being initialized. Then the analyzing is started. In the last step the PCAP is streamed to the Allegro Network Multimeter. Depending on the size of the PCAP the third step could take some time, but the Allegro Network Multimeter already allows access to the statistics of the already analyzed packets via web/API. | ||
The example assumes that PCAP parallel analysis is enabled in the global settings, so the PCAP analysis will be done in slot 1 and a dedicated ring buffer is available. | The example assumes that PCAP parallel analysis is enabled in the global settings, so the PCAP analysis will be done in slot 1 and a dedicated ring buffer is available. | ||
| Line 288: | Line 288: | ||
=== Virtual Link Groups === | === Virtual Link Groups === | ||
The Allegro REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled. | The Allegro Network Multimeter REST API allows to access all link groups by the parameter '''group'''. The group index starts at zero, which is the default value. If a virtual link group is enabled. | ||
This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ). | This example extracts the traffic of the IP 10.54.0.254 from the second virtual link group ( index 1 ). | ||
| Line 298: | Line 298: | ||
=== Parallel pcap analysis === | === Parallel pcap analysis === | ||
The Allegro can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given either the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> or the parameter mm-id with the PCAP instance ID. | The Allegro Network Multimeter can process in parallel offline traffic like a pcap file or a ring buffer. In case a parallel PCAP analysis is running, the API call must be given either the additional header field <code>"X-AllegroPackets-Multimeter-ID: :1"</code> or the parameter mm-id with the PCAP instance ID. | ||
This allows to extract information of automated pcap uploads. | This allows to extract information of automated pcap uploads. | ||
| Line 304: | Line 304: | ||
=== Multi-device analysis === | === Multi-device analysis === | ||
If the Allegro is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add either the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> or the parameter mm-id where the hostname must be the same as configured in the multi-device settings. | If the Allegro Network Multimeter is configured as a gateway for multiple Allegro devices by the [[Multi-device settings]], you need to add either the additional header field <code>"X-AllegroPackets-Multimeter-ID: hostname"</code> or the parameter mm-id where the hostname must be the same as configured in the multi-device settings. | ||
== REST API Examples == | == REST API Examples == | ||