API Tech Note - IP Fabric 4.x Unicast Path Lookup

This post is intended to explain the use of the IP Fabric Path Lookup API request, remodelled as part of the change in diagrams heralded by version 4.0.2 in October 2021.

API Endpoints

  • https://host.domain/api/v1/graphs - for JSON output

  • https://host.domain/api/v1/graphs/svg - for SVG vector image output

  • https://host.domain/api/v1/graphs/png - for PNG bitmap image output

POST Request

Requests are made using a POST to the endpoint listed above for the desired output. Headers must contain:

  • content-type: application/json

  • X-API-Token: (the API token provided from the IP Fabric Settings UI)

and the body of the request contains the JSON described in the next section.

Request Body

Contains a JSON data structure with the keys

  • "snapshot" [mandatory]- A quoted string containing the ID of the required snapshot. Can also use the reserved strings "$last", "$prev" and "$lastLocked"

  • "parameters" [mandatory]- A nested JSON data structure with keys

    • "type" [mandatory] - A quoted string with a value of "pathLookup" for an E2E path simulation output

    • "pathLookupType" [mandatory] - A quoted string containing the word "unicast" or "multicast" depending which type of path simulation you're wanting to execute

    • "protocol" [mandatory] - A quoted string with a value of "tcp", "udp", "icmp"

    • “vrf” [optional] - A quoted string containing the VRF identifier required

    • “flags” [optional] - an array of TCP flags to be set in the simulated path

    • "startingPoint" [mandatory]- A quoted string containing the source IP address

    • "startingPort" [mandatory]- An integer representing the source port

    • "destinationPoint" [mandatory]- A quoted string containing the destination IP address

    • "destinationPort" [mandatory]- An integer representing the destination port

    • "groupBy" [mandatory]- A quoted string representing the grouping of devices in the output - at this time one of "siteName", "routingDomain" or "stpDomain"

    • "networkMode" [mandatory]- A boolean - the new version of IP Fabric allows you to simulate paths between subnets. Setting this key to true means that you will create a single result representing the subnets; false means that IP Fabric will create a separate path for each source or destination in the range of addresses up to a maximum of 255.

    • "securedPath" [mandatory]- A boolean - when you run a path simulation, you can tell IP Fabric if you want to stop when it hits a security policy which blocks the traffic in question (true) or complete the forwarding paht and simply highlight the policy enforcement point (false)

  • positions [optional] - A nested JSON data structure consisting of keys representing the serial number of devices and their positions in the completed diagram. Origin of x=0, y=0 is the top left of the resulting image. Sample position data structure:

1 2 3 4 5 6 7 8 { "positions": { "SNXXXXXXXXX": { "x": 40, "y": 160 } } }
  • settings [optional] - A nested JSON data structure representing visualisation settings to override the default view in IP Fabric's diagram canvas. In these settings, it is possible to:

    • change edge properties like colours and thickness of lines representing protocols and groups

    • group or ungroup edges, and make protocols visible or invisible

    • change labels on the edges and interfaces

    • hide certain device types.
      Example settings data structure:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "settings": { "edges": [ { "id": "6129bb53-d19d-47ee-8f45-8829073221c1", "name": "vxlan", "type": "pathLookupEdge", "grouped": false, "style": { "color": "#d4b524", "pattern": "solid", "thicknessThresholds": [2,4,8] }, "visible": true, "labels": ["intName","protocol"] } ] } }

Example minimal request body

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "snapshot": "$last", "parameters": { "type": "pathLookup", "pathLookupType": "unicast", "protocol": "tcp", "startingPoint": "", "startingPort": 10000, "destinationPoint": "", "destinationPort": 80, "groupBy": "siteName", "networkMode": false, "securedPath": false } }


If the PNG or SVG endpoints are selected, the request returns a binary file representing the desired output.

Using the /graphs endpoint, a successful request returns a JSON response of the form:

1 2 3 4 { "graphResult": {...}, "pathlookup": {...} }


The "graphResult" construct describes the detail of the topology of the end to end path through the network. It consists of three sections:

  • "settings" - echoes the settings from the request body or the system settings as they apply to line styles, colours, weights and labels; hidden device types and groupings

  • "boxLabels" - text labels for each of the groups

  • "graphData" - a JSON construct containing a list of nodes and edges in the topological view of the path. Takes the form:

1 2 3 4 { "nodes": {...}, "edges": {...} }

where "nodes" contains data relating to the individual nodes in the graph. Each one is assigned a "vDevice" ID but there is recorded in each its hostname as "label", it's "position", its serial number in the "sn" field and the device "type". Other key:value pairs relate to the inner workings of the IP Fabric graphing process. For example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "vDevice/111111111": { "boxId": "SITE1", "children": [], "graphType": "pathLookup", "id": "vDevice/111111111", "label": "HOSTNAME", "parentPath": null, "position": { "x": 200, "y": 160 }, "sn": "SNXXXXXXXX", "type": "switch" }

"edges" contains data relating to the connections between the nodes along the data path. Each one is assigned an ID consisting of a combination of the node ID and interface at each end of the edge. The JSON construct also includes labels for the ends and the centre of the line, graphical details like (x,y) positions of the line and arrowheads and the colours and style of the lines. The "severity_info" key:value pair contains the information about how the edge conforms to applied intent checks; and the "packet" subtree contains a list of the layered packet headers in the simulation as it passes through the edge - for example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 { "packet": [ { "dst": "dddd.dddd.dddd", "etherType": "ip", "src": "aaaa.aaaa.aaaa", "type": "ethernet", "vlan": 10 }, { "dst": [ "" ], "protocol": "tcp", "src": [ "" ], "type": "ip" }, { "dst": [ "80" ], "flags": [], "src": [ "10000" ], "type": "tcp" } ] }


The "pathlookup" construct describes the hop-by-hop forwarding and policy decisions that have been taken to get from source to destination. Notable key:value pairs within that construct include:

  • "eventSummary" - which highlights the success or failure of the path and the cause of any issues along the way.

    • "flags" will show if any policy has caused the traffic to fail to reach the destination (eg "acl-deny" or "zone-deny")

    • "topics" is a construct to represent the "Result" tab in the UI - it shows whether there have been ACL or firewall policies affecting the path, or any issues with forwarding behaviour. Positive values for the "0" key show that the decision has allowed traffic to pass; positive values for any of the other keys indicate a failure in the evaluation at some point

  • "decisions" - contains a record for each device in the path and the forwarding and policy decision it has to make in the path. For each device:

    • "trafficIn" is a representation of the ingress interface and the edge that it is connected to

    • "trafficOut" represents the egress interface and the edge that it sends traffic along towards the destination

    • "traces" contains the data to represent how that decision was taken - for example that might include:

      • "switching-nexthop" decision in a switch will require a MAC address table match;

      • an "ip-routing" decision in a router will require a routing table lookup and an ARP table ;

      • an "ip-routing" decision in a zone-based firewall will add in a security check to validate that policy allows the packet to pass;

      • an "mpls-switching" decision will validate the VRF, MPLS labels and push/pop behaviour in the label stack; and so on.

I've not given any specific examples here as they vary wildly depending on the specifics of your environment. There are also numerous additional fields in the "pathlookup" construct which will also be dependent on your particular path check. And there are some key:value pairs which have specific internal usage. But by using trial and error, you should be able to get a good handle on the behaviour of the path lookup using this guidance.

From this note, you can see just how much thought and detail has gone into the development of the path lookup process. Hopefully it illustrates how closely IP Fabric models the behaviour of the data plane of network devices to give an accurate view of the impact of the network on forwarding behaviour.


If you are interested in multicast or host-to-gateway path lookups, take a look at our other tech notes. The result will be the same but request body will use different parameters.