REST API Reference

  • Version 2 of the API allows granular querying of the data model via REST Calls
  • Most query options support Neo4j/JAVA style regexes
  • Base URL
  • /netgrph/api/v2

Setup

  • Configure the [api] section in netgrph.ini
  • Enable HTTPS using valid certs for serving API calls beyond localhost
  • Setup Process
  • Initialize the SQL Lite database: ./ctlsrv.py --initdb
  • Add an API User: ./ctlsrv --adduser testuser
  • Run the Server: ./ctlsrv.py --run
  • Test a Query: curl -u testuser:testpass http://localhost:4096/netgrph/api/v2/devs

Examples

Switch path

$ curl -u testuser:testpass 'http://localhost:4096/netgrph/api/v2/spath?src=mdcmdf&dst=core1'
{
  "Distance": 1,
  "Links": 1,
  "Name": "mdcmdf -> core1",
  "Search Depth": "20",
  "Traversal Type": "All Paths",
  "_ccount": 1,
  "_type": "L2-PATH",
  "data": [
    {
      "From Channel": "0",
      "From Model": "WS-C3850-48U",
      "From Port": "Te1/1/4",
      "From Switch": "mdcmdf",
      "Link VLANs": "1246,2200,2314,2320,2324,2365,2376",
      "Link rVLANs": "1246,2200,2314,2320,2324,2365,2376",
      "Name": "#1 mdcmdf(Te1/1/4) -> core1(Eth10/21)",
      "Native VLAN": "2200",
      "To Channel": "0",
      "To Model": "Nexus7000 C7010",
      "To Port": "Eth10/21",
      "To Switch": "core1",
      "_ccount": 0,
      "_cversion": "03.06.04.E RELEASE SOFTWARE (fc2)",
      "_pversion": "Version 6.2(16)",
      "_reverse": 1,
      "_rvlans": "1246,2200,2314,2320,2324,2365,2376",
      "_type": "L2-HOP",
      "data": [],
      "distance": 1
    }
  ]
}

Networks on a filter (guest VRF with guest access role)

curl -u testuser:testpass 'http://localhost:4096/netgrph/api/v2/nets?filter=guest:nac-guest'
{
  "Count": 23,
  "Filter": "guest:nac-guest",
  "Name": "Networks",
  "_ccount": 23,
  "_type": "NET",
  "data": [
    {
      "CIDR": "10.29.2.0/23",
      "Description": "None",
      "Gateway": "10.29.2.1",
      "Location": null,
      "Name": "10.29.2.0/23",
      "NetRole": "nac-guest",
      "Router": "mdcmdf",
      "SecurityLevel": "10",
      "StandbyRouter": null,
      "VLAN": "270",
      "VRF": "guest",
      "_type": "CIDR",
      "vrfcidr": "guest-10.29.2.0/23"
    },

Device Calls

Device Queries allow you to query the API for all devices, regexes and gather specific information from individual devices.

  • URLs
  • /devs: List all Devices
  • /devs/{device}: Specific Device
  • /devs/{device}/vlans: Device VLANs
  • /devs/{device}/neighbors: Device Neighbors

  • /devs/{device}/nets: Device Networks

  • Method:

  • GET

  • URL Parameters

  • group: Restrict on device group regex
  • search: Restrict on device name regex

  • full: Return full device reports (non-truncated and slower)

  • Success Response:

  • Code: 200
    Content: { Name : Report, _type : "VIDs" }

  • Error Response:

  • Code: 401
    Content: { message : "Request Error" }

Network Calls

Network Queries allow you to query for networks based on CIDRs, VRF, Role and Group filters.

  • URLs
  • /nets: List of All Networks
  • /nets?group=X&cidr=X: Networks filtered on group and cidr

  • /nets?ip=X: Most Specific CIDR from IP

  • Method:

  • GET

  • URL Parameters

  • group: Restrict on device group regex
  • cidr: Restrict on device name regex (optionally replace /24 mask with -24)
  • filter: Filter via NetGrph vrf:role syntax

  • ip: Find most specific CIDR for IP

  • Success Response:

  • Code: 200
    Content: { Name : Report, _type : "Networks" }

  • Error Response:

  • Code: 401
    Content: { message : "Request Error" }

VLAN Calls

VLAN Queries return lists of all VLANs, specific VLAN trees and VLANs for groups

  • URLs
  • /vlans: Retrieve All VLANs

  • /vlans/<vlan>: Retrieve Specific VLAN in VID or VNAME Format

  • URL Parameters

  • group: VLANs in a Management Group

  • range: VLAN Range eg. 1-1005

  • Success Response:

  • Code: 200
    Content: { Name : Report, _type : "VLANs" }

  • Error Response:

  • Code: 401
    Content: { message : "Request Error" }

Path Calls

Path queries allow you to do L2-L4 traversals between any two points on the network.

  • URLs
  • /path?src=[ip]&dst=[ip]: Universal L2-L4 Path Query
  • /spath?src=[switch]&dst[switch.*]: Switch paths using a regex
  • /rpath?src=[ip]&dst=[ip]&vrf=pci: L3 Path inside a VRF

  • /fpath?src=[ip]&dst=[ip]: L4 Path Query

  • URL Parameters

  • src(required): Source of Path Query (regex support on switch paths)
  • dst(required): Destination of Path Query
  • onepath(set True): Only show one path, no ECMP
  • depth: Depth of Graph Search (default 20)
  • vrf: VRF for Routed Queries

  • Note: src and dst support regexes on switch paths

  • Method:

  • GET

  • Success Response:

  • Code: 200
    Content: { Name : Report, _type : "PATH" }

  • Error Response:

  • Code: 401
    Content: { message : "Request Error" }