NBI path API

NBI path API allows to trace possible paths in discovered network topology considering extra constraints.

Usage

POST /api/nbi/path

Trace k-shortest paths over network topology considering constraints.

Example Request:

POST /api/nbi/path  HTTP/1.1
Host: noc.example.com
Private-Token: 12345

{
    "from": <path start specification>,
    "to": <path end specification>,
    "config": <path config specification>,
    "constraints": <path constraint specification>
}

Example Response

HTTP/1.1 200 OK
Content-Type: text/json

{
    "status": true,
    "time": 0.012,
    "paths": [
        {
            "path": [
                {
                    "links": [
                        {
                            "objects": [
                                {
                                    "interfaces": [
                                        "Eth 1/27"
                                    ],
                                    "object": {
                                        "address": "172.11.101.209",
                                        "bi_id": 1362320908973547200,
                                        "id": 40046,
                                        "name": "sw1"
                                    }
                                },
                                {
                                    "interfaces": [
                                        "Eth 1/52"
                                    ],
                                    "object": {
                                        "address": "172.11.103.20",
                                        "bi_id": 6072199926162248000,
                                        "id": 17918,
                                        "name": "sw2"
                                    }
                                }
                            ]
                        },
                        ...
                    ]
                },
                ...
            ],
            "cost": {
                "l2": 6
            }
        },
        ...
    ]
}
Request JSON Object:
 
Response JSON Object:
 
  • status (boolean) – Request status, true if success
  • error (string) – Error text, only if status is false.
  • time (float) – Request processing time in seconds.
  • paths (array) – Paths found, only if status is true.
Request Headers:
 
  • Private-TokenAPI Key with nbi:path API access
Status Codes:

Path Start Specification

Path Start specified as value of from request key and can be either Managed Object, interface or service reference.

Managed Object By Id

{
    "object": {
        "id": 12345
    }
}

Where 12345 is the Managed Object Id

Managed Object By Id and Interface Name

{
    "object": {
        "id": 12345
    },
    "interface": {
        "name": "Gi 0/1"
    }
}

Where 12345 is the Managed Object Id and Gi O/1 is the normalized interface name.

Managed Object By Remote Id

{
    "object": {
        "remote_system": "6789",
        "remote_id": "1011"
    }
}

Where 6789 is the Remote System Id and 1011 is the Managed Object Id in Remote System.

Managed Object By Remote Id and Interface

{
    "object": {
        "remote_system": "6789",
        "remote_id": "1011"
    },
    "interface": {
        "name": "Gi 0/1"
    }
}

Where 6789 is the Remote System Id, 1011 is the Managed Object Id in Remote System and Gi O/1 is the normalized interface name.

Interface by Id

{
    "interface": {
        "id": "1234567"
    }
}

Where 1234567 is the Interface Id

Service by Id

{
    "service": {
        "id": 12345
    }
}

Where 12345 is the Service Id

Service by Remote Id

{
    "service": {
        "remote_system": "6789",
        "remote_id": "1011"
    }
}

Where 6789 is the Service Id and 1011 is the Service Id in Remote System.

Path End Specification

Path End specified as value of to request key.

  • Explicit specification
    • Managed Object
    • Interface
    • Service
  • Implicit specification
    • Object level

Managed Object By Id

{
    "object": {
        "id": 12345
    }
}

Where 12345 is the Managed Object Id

Managed Object By Id and Interface Name

{
    "object": {
        "id": 12345
    },
    "interface": {
        "name": "Gi 0/1"
    }
}

Where 12345 is the Managed Object Id and Gi O/1 is the normalized interface name.

Managed Object By Remote Id

{
    "object": {
        "remote_system": "6789",
        "remote_id": "1011"
    }
}

Where 6789 is the Remote System Id and 1011 is the Managed Object Id in Remote System.

Managed Object By Remote Id and Interface

{
    "object": {
        "remote_system": "6789",
        "remote_id": "1011"
    },
    "interface": {
        "name": "Gi 0/1"
    }
}

Where 6789 is the Remote System Id, 1011 is the Managed Object Id in Remote System and Gi O/1 is the normalized interface name.

Interface by Id

{
    "interface": {
        "id": "1234567"
    }
}

Where 1234567 is the Interface Id

Service by Id

{
    "service": {
        "id": 12345
    }
}

Where 12345 is the Service Id

Service by Remote Id

{
    "service": {
        "remote_system": "6789",
        "remote_id": "1011"
    }
}

Where 6789 is the Service Id and 1011 is the Service Id in Remote System.

By Object Level

{
    "level": 30
}

Specify path end by reaching Managed Object Level greater than specified.

Path Config Specification

Path Config specified as value of config request key.

{
    "max_depth": 10,
    "n_shortest": 2
}

Where:

  • max_depth - Restrict search depth up to max_depth nodes.
  • n_shortest - Return up to n_shortest paths.

Path Constraints Specification

Path Constraints are specified as value of constraints request key.

Explicit VLAN

{
    "vlan": {
        "vlan": 1234,
        "strict": false
    }
}

Restrict paths to links having VLAN 1234, either tagged or untagged. strict parameter enforces additional checking:

  • true - VLAN must be present on both sides of the link.
  • false - VLAN must be present at least on one side of the link.

Implicit VLAN

{
    "vlan": {
        "interface_untagged": true,
        "strict": true
    }
}

Get untagged vlan from start of path interface and restrict path to links having this VLAN, either tagged or untagged.

strict parameter enforces additional checking:

  • true - VLAN must be present on both sides of the link.
  • false - VLAN must be present at least on one side of the link.

Upward Direction

{
    "upwards": true
}

Forces upward direction of path. i.e. Managed Object Level of each next object of the path may not be less that level of current object. Effectively speed-ups path finding by denying descending to lower levels of networks.