Flow Classification API

Use the Flow Classification API to update, create, or delete flow classification rules.

If not otherwise specified, the Content-Type of the response is application/json.

GETs (reading data)

Flow Classification API GET functions
Resource	Description
/classifications	Retrieve a list of all enabled rules. The request is limited to `10` items by default. Setting `limit` to `0` returns all enabled rules.
/classifications/{id}	Retrieve the rule identified by `{id}`.
/classifications/groups	Retrieve all existing groups. The request is limited to `10` items by default. Setting `limit` to `0` returns all enabled rules.
/classifications/groups/{id}	Retrieve the group identified by {id}` Supports downloading all rules of the given group in CSV format. For this, set the accept header: `Accept: text/comma-separated-values`.
/classifications/protocols	Retrieve all supported TCP protocols.

The /classifications endpoint supports the following URL parameters:

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

Flow Classification API GET functions
Name	Default Value	Comment
groupFilter	Empty	The group by which to filter the rules. Should be the `id` retrieved by `/classifications/groups`. It is not possible to retrieve the rules for a disabled group.
query	Empty	A `string` to query a rule by `port` OR `ipAddress` or `name` or `protocol`. Must not contain `%` or `*` to perform a like query.

Examples

Retrieve all enabled rules

curl -X GET -u admin:admin http://localhost:8980/opennms/rest/classifications

Response

[
    {
        "group": {
            "description": "Classification rules defined by the user",
            "enabled": true,
            "id": 2,
            "name": "user-defined",
            "position": 10,
            "readOnly": false,
            "ruleCount": 1
        },
        "id": 1,
        "ipAddress": null,
        "name": "http",
        "port": "80",
        "position": 0,
        "protocols": [
            "TCP"
        ]
    }
]

Retrieve all groups

curl -X GET -u admin:admin http://localhost:8980/opennms/rest/classifications/groups

Response

[
    {
        "description": "Classification rules defined by OpenNMS",
        "enabled": false,
        "id": 1,
        "name": "pre-defined",
        "priority": 0,
        "readOnly": true,
        "ruleCount": 6248
    },
    {
        "description": "Classification rules defined by the user",
        "enabled": true,
        "id": 2,
        "name": "user-defined",
        "priority": 10,
        "readOnly": false,
        "ruleCount": 1
    }
]

Retrieve specific rule

curl -X GET -u admin:admin http://localhost:8980/opennms/rest/classifications/1

Response

{
    "group": {
        "description": "Classification rules defined by the user",
        "enabled": true,
        "id": 2,
        "name": "user-defined",
        "priority": 10,
        "readOnly": false,
        "ruleCount": 1
    },
    "id": 1,
    "ipAddress": null,
    "name": "http",
    "port": "80",
    "position": 0,
    "protocols": [
        "TCP"
    ]
}

Retrieve specific group

curl -X GET -H "Accept: application/json"  -u admin:admin http://localhost:8980/opennms/rest/classifications/groups/1

Response

{
    "description": "Classification rules defined by OpenNMS",
    "enabled": false,
    "id": 1,
    "name": "pre-defined",
    "priority": 0,
    "readOnly": true,
    "ruleCount": 6248
}

Retrieve group as CSV

curl -X GET -H "Accept: text/comma-separated-values" -u admin:admin http://localhost:8980/opennms/rest/classifications/groups/2

Response

name;ipAddress;port;protocol
http;;80;TCP

POSTs (creating data)

Flow Classification API POST functions
Resource	Description
/classifications	Post a new rule or import rules from CSV. If multiple rules are imported (to user-defined group) from a CSV file all existing rules are deleted.
/classifications/classify	Classify the given request based on all enabled rules.

Examples

Create a single rule

curl -X POST -H "Content-Type: application/json" -u admin:admin -d '{"name": "http", "port":"80,8080", "protocols":["tcp", "udp"]}' http://localhost:8980/opennms/rest/classifications

Response

HTTP/1.1 201 Created
Date: Thu, 08 Feb 2018 14:44:27 GMT
Location: http://localhost:8980/opennms/rest/classifications/6616

Verify classification engine (rule exists)

curl -X POST -H "Content-Type: application/json" -u admin:admin -d '{"protocol": "tcp", "ipAddress": "192.168.0.1", "port" :"80"}' http://localhost:8980/opennms/rest/classifications/classify

Response

{
  "classification":"http"
}

Verify classification engine (no rule exists)

curl -X POST -H "Content-Type: application/json" -u admin:admin -d '{"protocol": "tcp", "ipAddress": "192.168.0.1", "port" :"8980"}' http://localhost:8980/opennms/rest/classifications/classify

Response

HTTP/1.1 204 No Content

Import rules from CSV

curl -X POST -H "Content-Type: text/comma-separated-values" -u admin:admin -d $'name;ipAddress;port;protocol\nOpenNMS;;8980;tcp,udp\n' http://localhost:8980/opennms/rest/classifications/groups/\{id}\?hasHeader\=true

Response

HTTP/1.1 204 No Content

Import rules from CSV (data with errors)

curl -X POST -H "Content-Type: text/comma-separated-values" -u admin:admin -d $'OpenNMS;;INCORRECT;tcp,udp\nhttp;;80,8080;ULF' http://localhost:8980/opennms/rest/classifications\?hasHeader\=false

Response

{
    "errors": {
        "1": {
            "context": "port",
            "key": "rule.port.definition.invalid",
            "message": "Please provide a valid port definition. Allowed values are numbers between 0 and 65536. A range can be provided, e.g. \"4000-5000\", multiple values are allowed, e.g. \"80,8080\""
        },
        "2": {
            "context": "protocol",
            "key": "rule.protocol.doesnotexist",
            "message": "The defined protocol 'ULF' does not exist"
        }
    },
    "success": false
}

PUTs (updating data)

Flow Classification API PUT functions
Resource	Description
/classifications/{id}	Update a rule identified by `{id}`. The ID of the rule cannot be changed.
/groups/{id}	Retrieve the rule identified by `{id}`.
/classifications/groups	Update a group. Currently, only the enabled property can be changed.

DELETEs (deleting data)

Flow Classification API DELETE functions
Resource	Description
/classifications?groupId={groupid}	Deletes all rules of a given group.
/groups/{id}	Delete the given group and all its containing rules.