REST API description

General

All Allegro Network Multimeter statistics are derived from HTTP requests and provided as JSON objects. The requests are stateless, i.e. there are no prerequisites and there is no fixed sequence of requests necessary. Example requests related to a specific module and statistics can be seen in the web interface by opening the browser development console (Ctrl+Shift+I for Chrome and Firefox, F12 for Edge). The credentials are the same as for the web interface. A non-admin user has read access to most of the statistics.

Examples

In this section some examples are given using PowerShell and Linux curl and jq commands.

SSL certificate errors

If the default self-signed SSL certificate is used, curl and PowerShell will display error messages. You can either install another SSL certificate or let the tools ignore the errors. For curl it is:

curl -k ...

For PowerShell in recent versions (v6 and later) it is:

Invoke-RestMethod -SkipCertificateCheck ...

MAC or IP address statistics

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff' curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3'

Pretty displaying JSON output with jq

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq

Traffic counters

Traffic counters are represented as a JSON array with at least 4 lines. The structure is as follows:

• line 1: received packets.
• line 2: received bytes.
• line 3: transmitted packets.
• line 4: transmitted bytes.
• other lines are module specific.

The following counters are supported:

• interval: Values of the selected time interval. If no interval is specified, this is similar to lastSecond.
• allTime: Values since start of the Allegro Network Multimeter.
• lastSecond: Values of the last second.
• intervalPerSecond: Average per second value of the selected time interval. If no interval is specified, this is similar to lastSecond.

Time interval selection

Requests can be given a time interval. The following GET parameters are necessary:

• starttime, endtime: Start and end time of the interval. Format: seconds since 1970/01/01 UTC (Unix time, epoch).
• timespan: Duration of the interval selection in seconds.

Extract received bytes of the last second of a specific IP

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq .lastSecond[1]

Extract received and transmitted bytes of the last second of a specific IP

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq '.lastSecond[1] + .lastSecond[3]'

Extract received and transmitted bytes in a time interval (18/06/11 9:00 - 10:00) of a specific IP

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3?timespan=3600&starttime=1528700400&endtime=1528704000' | jq '.interval[1] + .interval[3]'

List queries

List queries are requested with pagination parameters to reduce the size of the resulting JSON objects and to increase performance. In the resulting JSON object, the list elements are stored in the displayedItems array. The following list parameters are possible:

• sort: Sorting criteria for the list. Following criterias are supported for most lists:
  • bytes: Received and transmitted bytes (either in selected time interval or since start of the Multimeter).
  • rxbytes: Received bytes.
  • txbytes: Transmitted bytes.
  • bps: Received and transmitted bytes per second (either average per second value of the selected time interval or last second, if no interval is specified).
  • rxbps: Received bytes per second.
  • txbps: Transmitted bytes per second.
• reverse: Sort ascending (= false) or descending (= true).
• page: Requested page.
• count: Amount of entries in the list. Maximum is 100.
• values: Amount of maximal values in history object(s).

Show IP address with the highest amount of traffic

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips_paged?sort=bps&reverse=true&page=0&count=1' | jq .displayedItems[0].ip

PowerShell command:

((Invoke-RestMethod -Uri 'https://allegro-mm-XXXX/API/stats/modules/ip/ips_paged?sort=bytes&reverse=true&page=0&count=10&timespan=60&values=50' -Headers @{Authorization = ("Basic {0}" -f [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f 'USER', 'PASSWORD'))))} -ContentType'application/json; charset=utf-8' -Method 'Get' -SkipCertificateCheck). displayedItems[0]).ip

Show all peers of a specific IP address

curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3/peers?sort=bytes&reverse=true&page=0&count=9999&timespan=60&values=100' | jq '.displayedItems[].ip'

Capture a specific IP

curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/data/modules/capture?expression=ip==10.1.2.3' > path_to/capture.pcap

Capture two IP addresses with ports on a specific Layer 4 protocol

curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/data/modules/capture?expression=IP==10.1.2.3:62887 and IP==10.1.2.100:548 and l4Protocol==TCP' > path_to/capture.pcap

Pcap parameters

The following parameters are possible:

• startTime: The start time of the capture. The first packet with exactly this or a later time will start the capture. The time format must be microseconds after January, 1st 1970 UTC (Unix time, epoch).

If the start time is in the past, make sure you set fromCaptureBuffer parameter accordingly.

• endTime: The end time of the capture. The first packet with exactly this or a later time will stop the capture.

The time format must be microseconds after January, 1st 1970 UTC (Unix time, epoch).

• expression: The filter expression. There are no whitespaces allowed. You may use ‘%20’ instead.
• snapPacketLength: The maximum size of a packet applied on Layer 2 without frame check sequence. If a packet is larger than this value, it is truncated. Use 65535 for unlimited size.
• fromCaptureBuffer: Whether to extract data from the packet ring buffer (= true) or just live traffic (= false).
• captureToMedia: Whether to store a pcap on an external storage device (= true) or download to your computer (= false).