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)

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.
Name Default Comment

groupFilter

(none)

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

(none)

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)

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)

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. At the moment, only the enabled property can be changed.

DELETEs (Deleting Data)

Resource Description

/classifications?groupId={groupid}

Deletes all rules of a given group.

/groups/{id}

Delete the given group and all its containing rules.