
= Flow API

Use the Flow API to retrieve summary statistics and time series data derived from persisted flows.

NOTE: Unless otherwise specified, all units of time are expressed in milliseconds.

== GETs (reading data)

[caption=]
.Flow API GET functions
[options="autowidth"]
|===
| Resource  | Description

| /flows/count
| Retrieve the number of flows available.

| /flows/exporters
| Retrieve basic information for the exporter nodes that have flows available.

| /flows/exporters/\{nodecriteria}
| Retrieve detailed information about a specific exporter node.

| /flows/applications
| Retrieve traffic summary statistics for the top `N` applications or specific applications.

| /flows/applications/enumerate
| Retrieve a list of the applications with flows.

| /flows/applications/series
| Retrieve time series metrics for the top `N` applications or specific applications.

| /flows/conversations
| Retrieve traffic summary statistics for the top `N` conversations or specific conversations.

| /flows/conversations/enumerate
| Retrieve a list of the conversations with flows.

| /flows/conversations/series
| Retrieve time series metrics for the top `N` conversations or specific conversations.

| /flows/hosts
| Retrieve traffic summary statistics for the top `N` hosts or specific hosts.

| /flows/hosts/enumerate
| Retrieve a list of the hosts with flows.

| /flows/hosts/series
| Retrieve time series metrics for the top `N` hosts or specific hosts.
|===

All of the endpoints support the following query string parameters to help filter the results:

[options="autowidth"]
|===
| Name  | Default Value | Comment

| start
| -14400000
| Timestamp. +
If > `0`, the timestamp is relative to the UNIX epoch (January 1st 1970 00:00:00 AM). +
If < `0`, the timestamp is relative to the `end` option (for example, default value is 4 hours ago).

| end
| 0
| Timestamp.
If \<= `0`, the effective value will be the current timestamp.

| ifIndex
| _Blank_
| Filter for flows that came in through the given SNMP interface.

| exporterNode
| _Blank_
| Filter for flows that were exported by the given node. +
Support either node ID (for example, `1`), or foreign source and foreign ID lookups (for example, `FS:FID`).
|===

NOTE: The given filters are combined using a logical `AND`.
There is no support for using `OR` logic, or combinations thereof.

The `exporters` endpoints do not support any parameters.

The `applications/enumerate` endpoint also supports:

[options="autowidth"]
|===
| Name  | Default Value | Comment

| limit
| 10
| Number of applications with flows to return.

| prefix
| _Blank_
| If provided, filters the results to include only applications with names that start with the given prefix (using fuzzy matching).
|===

The `applications` and `applications/series` endpoints also support:

[cols="1,1,3"]
|===
| Name  | Default Value | Comment

| N
| _Blank_
| Number of top entries (determined by total bytes transferred) to return.

| includeOther
| false
| When set to `true`, the results will also include an additional row or column that contains the bytes transferred for the flows that fall outside of the selected set.

| application
| _Blank_
| If provided, returns only flow series that match the given applications.
This field can be repeated for any number of applications to be included in the query.
|===

Both endpoints require one of `N` or `application` query parameters to be set and will return an error if neither or both are set.

The `conversations/enumerate` endpoint also supports:

[options="autowidth"]
|===
| Name  | Default Value | Comment

| limit
| 10
| Number of hosts with flows to return.

| location
| ".*"
| If provided, filters the results to include only conversations that match the given location regex pattern.

| protocol
| ".*"
| If provided, filters the results to include only conversations that match the given protocol regex pattern.

| lower
| ".*"
| If provided, filters the results to include only conversations that match the given lower IP address regex pattern.

| upper
| ".*"
| If provided, filters the results to include only conversations that match the given upper IP address regex pattern.

| application
| ".*"
| If provided, filters the results to include only conversations that match the given application regex pattern.
|===

The `conversations` and `conversations/series` endpoints also support:

[cols="1,1,3"]
|===
| Name  | Default Value | Comment

| N
| 10
| Number of top entries (determined by total bytes transferred) to return.

| includeOther
| false
| When set to `true` the results will also include an additional row or column that contains the bytes transferred for the flows that fall outside of the selected set.

| conversation
| _Blank_
| If provided, returns only flow series that match the given conversations.
This field can be repeated for any number of conversations to include in the query.

| hostname_mode
| replace
a| Controls how IP addresses are replaced with hostnames if available:

* `replace` will replace the IP address with the hostname.
* `append` will append the hostname to the IP address.
* `hide` will not show the hostname at all.
|===

NOTE: Make sure to URL encode the conversation value in your request.

Both endpoints require one of `N` or `conversation` query parameters to be set and will return an error if neither or
both are set.

The `conversations/series` endpoint also supports:

[options="autowidth"]
|===
| Name  | Default Value | Comment

| step
| 300000
| Requested time interval between rows.
|===

The `hosts/enumerate` endpoint also supports:

[options="autowidth"]
|===
| Name  | Default Value | Comment

| limit
| 10
| Number of hosts with flows to return.

| pattern
| ".*"
| If provided, filters the results to include only hosts with names that match the given regex pattern.
|===

The `hosts` and `hosts/series` endpoints also support:

[cols="1,1,3"]
|===
| Name  | Default Value | Comment

| N
| _Blank_
| Number of top entries (determined by total bytes transferred) to return.

| includeOther
| false
| When set to `true`, the results will also include an additional row or column that contains the bytes transferred for the flows that fall outside of the selected set.

| host
| _Blank_
| If provided, returns only flow series that match the given hosts.
This field can be repeated for any number of hosts to be included in the query.
|===

Both endpoints require one of `N` or `host` query parameters to be set and will return an error if neither or
both are set.

=== Examples

.Retrieve the number of flows persisted in the last 4 hours
[source,bash]
----
curl -u admin:admin http://localhost:8980/opennms/rest/flows/count
----

.Response
[source,javascript]
----
915
----

.Retrieve traffic summary for top 10 applications in the last 4 hours
[source,bash]
----
curl -u admin:admin http://localhost:8980/opennms/rest/flows/applications
----

.Response
[source,javascript]
----
{
	"start": 1513788044417,
	"end": 1513802444417,
	"headers": ["Application", "Bytes In", "Bytes Out"],
	"rows": [
		["https", 48789, 136626],
		["http", 12430, 5265]
	]
}
----

.Retrieve traffic summary for top 10 conversations in the last 4 hours
[source,bash]
----
curl -u admin:admin http://localhost:8980/opennms/rest/flows/conversations
----

.Response
[source,javascript]
----
{
	"start": 1513788228224,
	"end": 1513802628224,
	"headers": ["Location", "Protocol", "Source IP", "Source Port", "Dest. IP", "Dest. Port", "Bytes In", "Bytes Out"],
	"rows": [
		["Default", 17, "10.0.2.15", 33816, "172.217.0.66", 443, 12166, 117297],
		["Default", 17, "10.0.2.15", 32966, "172.217.0.70", 443, 5042, 107542],
		["Default", 17, "10.0.2.15", 54087, "172.217.0.67", 443, 55393, 5781],
		["Default", 17, "10.0.2.15", 58046, "172.217.0.70", 443, 4284, 46986],
		["Default", 6, "10.0.2.15", 39300, "69.172.216.58", 80, 969, 48178],
		["Default", 17, "10.0.2.15", 48691, "64.233.176.154", 443, 8187, 39847],
		["Default", 17, "10.0.2.15", 39933, "172.217.0.65", 443, 1158, 33913],
		["Default", 17, "10.0.2.15", 60751, "216.58.218.4", 443, 5504, 24957],
		["Default", 17, "10.0.2.15", 51972, "172.217.0.65", 443, 2666, 22556],
		["Default", 6, "10.0.2.15", 46644, "31.13.65.7", 443, 459, 16952]
	]
}
----

.Retrieve time series data for top 3 applications in the last 4 hours
[source,bash]
----
curl -u admin:admin http://localhost:8980/opennms/rest/flows/applications/series?N=3&includeOther=true&step=3600000
----

.Response
[source,javascript]
----
{
    "start": 1516292071742,
    "end": 1516306471742,
    "columns": [
        {
            "label": "domain",
            "ingress": true
        },
        {
            "label": "https",
            "ingress": true
        },
        {
            "label": "http",
            "ingress": true
        },
        {
            "label": "Other",
            "ingress": true
        }
    ],
    "timestamps": [
        1516291200000,
        1516294800000,
        1516298400000
    ],
    "values": [
        [9725, 12962, 9725],
        [70665, 125044, 70585],
        [10937,13141,10929],
        [1976,2508,2615]
    ]
}
----

.Retrieve time series data for top 3 conversations in the last 4 hours
[source,bash]
----
curl -u admin:admin http://localhost:8980/opennms/rest/flows/conversations/series?N=3&step=3600000
----

.Response
[source,javascript]
----
{
    "start": 1516292150407,
    "end": 1516306550407,
    "columns": [
        {
            "label": "10.0.2.15:55056 <-> 152.19.134.142:443",
            "ingress": false
        },
        {
            "label": "10.0.2.15:55056 <-> 152.19.134.142:443",
            "ingress": true
        },
        {
            "label": "10.0.2.15:55058 <-> 152.19.134.142:443",
            "ingress": false
        },
        {
            "label": "10.0.2.15:55058 <-> 152.19.134.142:443",
            "ingress": true
        },
        {
            "label": "10.0.2.2:61470 <-> 10.0.2.15:8980",
            "ingress": false
        },
        {
            "label": "10.0.2.2:61470 <-> 10.0.2.15:8980",
            "ingress": true
        }
    ],
    "timestamps": [
        1516294800000,
        1516298400000
    ],
    "values": [
        [17116,"NaN"],
        [1426,"NaN"],
        [20395,"NaN",
        [1455,"NaN"],
        ["NaN",5917],
        ["NaN",2739]
    ]
}
----
