JSON API

Andrew R. Lake edited this page Jun 16, 2014 · 3 revisions
Clone this wiki locally

This page documents the request options and response format of the service that dumps the contents of a perfSONAR Topology service as JSON.

Service URL(s)

JSON Response

Top-level Fields

Field Type Description
status string Either "success" or "error". If "success" then it was able to grab the topology. If "error" it was unable to grab and/or parse the topology.
message string A human-readable description of an error.
domains array of "domin" objects A list of objects that represent the topology of a domain. Each domain contains connectivity information about thenetwork it represents.
circuits array of objects A list of circuits and the paths they take.

Domain Fields

Field Type Description
id string A URN that identifies the domain (e.g. urn:ogf:network:domain=es.net).
nodes array of "node" objects This list of "nodes", generally equivalent to routers or switches, in a given domain

Node Fields

Field Type Description
id string A URN that identifies the node (e.g. urn:ogf:network:domain=es.net:node=albu-cr1).
address string An IP address or hostname that may represent a loopback of management address of the device represented by the node
name string A descriptive name of the device represented by the node
hostName string The DNS hostName of a device represented by the node
latitude string The angular distance of node north or south of the earth's equator expressed in degrees
longitude string he angular distance of the node east or west of the meridian at Greenwich, England, or west of the standard meridian of a celestial object, expressed in degrees
ports array of "port" objects This list of "ports", generally equivalent to an interface (virtual or physical) on a router or switch

Port Fields

Field Type Description
id string A URN that identifies the port (e.g. urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-2/0/1).
capacity integer bandwidth of the port in bps
maximumReservableCapacity integer the maximum amount of bandwidth that can be reserved by circuits in bps
minimumReservableCapacity integer the minimum amount of bandwidth that can be reserved by a circuit in bps
granularity integer the increments that bandwidth can be reserved by a circuit in bps
ifName string the name of the interface this port represents
ifDescription string the description of the interface this port represents
ipAddress string the IP address of the interface this port represents
netmask string the netmask of the interface this port represents
over string if this port is a virtual port or a sub-port, this is the ID of the underlying physical port
links list of "link" objects A list of objects that describe how this port connects to another port

Link Fields

Field Type Description
id string A URN that identifies the link (e.g. urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-2/0/1:link=*).
name string An IP or hostname that represents a link
nameType string Indicates whether this is a "logical" name.
type string Explicitly says "unidirectional" if its not bidirectional. It's null otherwise.
remoteLinkId string The URN indicating to what this link connects. It should be an ID of another link. If it's urn:ogf:network:domain=:node=:port=:link= then it doesn't know what's on the other end.
trafficEngineeringMetric integer A value used by pathfinding application to determine the "cost" of using a link. All else being equal, the lower the cost value then the more desirable a link is to a path computation algorithm trying to find the lowest cost path.
capacity integer bandwidth of the link in bps
maximumReservableCapacity integer the maximum amount of bandwidth that can be reserved by circuits in bps
minimumReservableCapacity integer the minimum amount of bandwidth that can be reserved by a circuit in bps
granularity integer the increments that bandwidth can be reserved by a circuit in bps
switchingcapType string ls2c for ethernet links, tdm for sdh/sonet links, and psc-4 for mpls links. Values are taken from GMPLS,
encodingType string ethernet for ethernet, sdh for SDH/SONET, and packet for MPLS and IP links. Taken from GMPLS.
vlanRangeAvailability string The VLANs circuits are allowed to reserve.
interfaceMTU string The MTU of the link
vlanTranslation boolean Indicates if link is capable of translating VLANs.

Circuit Fields

Field Type Description
id string A URN that is the globally unique identifier of the circuit. This is what perfSOANR theoretically uses to identify the circuit.
start integer unix timestamp of circuit start time
end integer unix timestamp of circuit end time
name string Another name for the circuit. In ESnet it corresponds to the ID OSCARS uses to identify the circuit at the web service layer.
description string A user-provided description of the circuit's purpose
segment_ids array of strings Circuits are composed of segments where a segment is the path across each domain, This is the ID each domain uses to identify its local segment of the circuit. There will be two for each domain, one for the forward direction and another for the reverse direction,
segments array of "segment" objects These are the details of each segment in the circuit.

Segment Fields

Field Type Description
id string Identifers of the sement. It should map to one of the ids in the parent circuit objects segment_ids list
ports list of strings An ordered list of the ports this segment uses (i.e. the first port is the ingress and the last is the egress, everything in the middle is the route data travels to get between them). The strings are URNS and should map to an id field of a object you will find in one of the domain objects.

Example JSON Response

{
   "status" : "success",
   "domains" : [
      {
         "nodes" : [
            {
               "ports" : [
                  {
                     "granularity" : 1000000,
                     "maximumReservableCapacity" : 500000000,
                     "minimumReservableCapacity" : 1000000,
                     "id" : "urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-1/2/0",
                     "capacity" : 1000000000,
                     "links" : [
                        {
                           "vlanRangeAvailability" : "2-908,910-918,920-4094",
                           "encodingType" : "packet",
                           "remoteLinkId" : "urn:ogf:network:es.net:albu-cr1:ge-1/2/0:site",
                           "vlanTranslation" : true,
                           "switchingcapType" : "",
                           "id" : "urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-1/2/0:link=*",
                           "type" : null,
                           "trafficEngineeringMetric" : "100",
                           "interfaceMTU" : "9000"
                        }
                     ]
                  },
                  {
                     "granularity" : 1000000,
                     "maximumReservableCapacity" : 500000000,
                     "minimumReservableCapacity" : 1000000,
                     "id" : "urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-2/0/0",
                     "capacity" : 1000000000,
                     "links" : [
                        {
                           "vlanRangeAvailability" : "0,2-4094",
                           "encodingType" : "packet",
                           "remoteLinkId" : "urn:ogf:network:es.net:snla-rt2:ge-1/3/0:ge-1/3/0.0",
                           "vlanTranslation" : true,
                           "switchingcapType" : "psc-4",
                           "id" : "urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-2/0/0:link=ge-2/0/0.0##134.55.218.125",
                           "type" : null,
                           "trafficEngineeringMetric" : "50000",
                           "interfaceMTU" : "9000"
                        }
                     ]
                  },
                  {
                     "granularity" : 1000000,
                     "maximumReservableCapacity" : 500000000,
                     "minimumReservableCapacity" : 1000000,
                     "id" : "urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-2/0/1",
                     "capacity" : 1000000000,
                     "links" : [
                        {
                           "vlanRangeAvailability" : "none",
                           "encodingType" : "packet",
                           "remoteLinkId" : "urn:ogf:network:es.net:albu-cr1:ge-2/0/1:site",
                           "vlanTranslation" : true,
                           "switchingcapType" : "",
                           "id" : "urn:ogf:network:domain=es.net:node=albu-cr1:port=ge-2/0/1:link=*",
                           "type" : null,
                           "trafficEngineeringMetric" : "100",
                           "interfaceMTU" : "9000"
                        }
                     ]
                  },
               ],
               "address" : "134.55.200.80",
               "id" : "urn:ogf:network:domain=es.net:node=albu-cr1"
            },
            {
               "ports" : [
                  {
                     "granularity" : 1000000,
                     "maximumReservableCapacity" : 5000000000,
                     "minimumReservableCapacity" : 1000000,
                     "id" : "urn:ogf:network:domain=es.net:node=albu-sdn1:port=xe-0/0/0",
                     "capacity" : 10000000000,
                     "links" : [
                        {
                           "vlanRangeAvailability" : "0,2-4094",
                           "encodingType" : "packet",
                           "remoteLinkId" : "urn:ogf:network:es.net:albu-cr1:xe-3/1/0:xe-3/1/0.0",
                           "vlanTranslation" : true,
                           "switchingcapType" : "psc-4",
                           "id" : "urn:ogf:network:domain=es.net:node=albu-sdn1:port=xe-0/0/0:link=xe-0/0/0.0##134.55.40.173",
                           "type" : null,
                           "trafficEngineeringMetric" : "1000",
                           "interfaceMTU" : "9000"
                        }
                     ]
                  },
                  {
                     "granularity" : 1000000,
                     "maximumReservableCapacity" : 10000000000,
                     "minimumReservableCapacity" : 1000000,
                     "id" : "urn:ogf:network:domain=es.net:node=albu-sdn1:port=xe-0/1/0",
                     "capacity" : 10000000000,
                     "links" : [
                        {
                           "vlanRangeAvailability" : "0,2-4094",
                           "encodingType" : "packet",
                           "remoteLinkId" : "urn:ogf:network:es.net:elpa-sdn1:xe-7/0/0:xe-7/0/0.0",
                           "vlanTranslation" : true,
                           "switchingcapType" : "psc-4",
                           "id" : "urn:ogf:network:domain=es.net:node=albu-sdn1:port=xe-0/1/0:link=xe-0/1/0.0##134.55.39.46",
                           "type" : null,
                           "trafficEngineeringMetric" : "50",
                           "interfaceMTU" : "9000"
                        }
                     ]
                  },
                  {
                     "granularity" : 1000000,
                     "maximumReservableCapacity" : 10000000000,
                     "minimumReservableCapacity" : 1000000,
                     "id" : "urn:ogf:network:domain=es.net:node=albu-sdn1:port=xe-1/0/0",
                     "capacity" : 10000000000,
                     "links" : [
                        {
                           "vlanRangeAvailability" : "0,2-4094",
                           "encodingType" : "packet",
                           "remoteLinkId" : "urn:ogf:network:es.net:albu-cr1:ge-5/0/0:ge-5/0/0.0",
                           "vlanTranslation" : true,
                           "switchingcapType" : "psc-4",
                           "id" : "urn:ogf:network:domain=es.net:node=albu-sdn1:port=xe-1/0/0:link=xe-1/0/0.0##134.55.40.185",
                           "type" : null,
                           "trafficEngineeringMetric" : "10",
                           "interfaceMTU" : "9000"
                        }
                     ]
                  },
               ],
               "address" : "134.55.200.69",
               "id" : "urn:ogf:network:domain=es.net:node=ameslab-rt2"
            },
         ],
         "id" : "urn:ogf:network:domain=es.net"
      },
      {
         "nodes" : [
            {
               "hostName" : "albu-cr1",
               "longitude" : "-106.646028",
               "ports" : [
                  {
                     "over" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=ge-1/2/0",
                     "ifDescription" : "albu-cr1->albu-owamp:10ge(vlan):access-local:show:intracloud",
                     "ipAddress" : "198.129.254.101",
                     "netmask" : "255.255.255.252",
                     "ifName" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=ge-1/2/0",
                     "id" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=198.129.254.101",
                     "links" : null
                  },
                  {
                     "ifDescription" : "albu-cr1->snla-rt2:ge:snla-ge:show:intracloud",
                     "ifName" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=ge-2/0/0",
                     "id" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=ge-2/0/0",
                     "capacity" : "1000",
                     "links" : [
                        {
                           "nameType" : "logical",
                           "remoteLinkId" : "urn:ogf:network:domain=ps.es.net:node=snla-rt2:port=ge-1/3/0:link=ge-1/3/0.0",
                           "name" : "134.55.218.125/255.255.255.252",
                           "type" : "unidirectional",
                           "id" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=ge-2/0/0:link=ge-2/0/0.0"
                        }
                     ]
                  },
               ],
               "latitude" : "+35.082833",
               "name" : "albu-cr1",
               "id" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1",
               "description" : "Juniper"
            },
            {
               "hostName" : "albu-sdn1",
               "longitude" : "-106.646774",
               "ports" : [
                  {
                     "ifDescription" : "albu-sdn1->albu-cr1:10ge(p2p):ip:show:intracloud",
                     "ifName" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/0/0",
                     "id" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/0/0",
                     "capacity" : "10000",
                     "links" : [
                        {
                           "nameType" : "logical",
                           "remoteLinkId" : "urn:ogf:network:domain=ps.es.net:node=albu-cr1:port=xe-3/1/0:link=xe-3/1/0.0",
                           "name" : "134.55.40.173/255.255.255.252",
                           "type" : "unidirectional",
                           "id" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/0/0:link=xe-0/0/0.0"
                        }
                     ]
                  },
                  {
                     "over" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/0/0",
                     "ifDescription" : "",
                     "ipAddress" : "134.55.40.173",
                     "netmask" : "255.255.255.252",
                     "ifName" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/0/0",
                     "id" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=134.55.40.173",
                     "links" : null
                  },
                  {
                     "ifDescription" : "albu-sdn1->elpa-sdn1:10ge(p2p):sdn-a:show:intracloud",
                     "ifName" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/1/0",
                     "id" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/1/0",
                     "capacity" : "10000",
                     "links" : [
                        {
                           "nameType" : "logical",
                           "remoteLinkId" : "urn:ogf:network:domain=ps.es.net:node=elpa-sdn1:port=xe-7/0/0:link=xe-7/0/0.0",
                           "name" : "134.55.39.46/255.255.255.252",
                           "type" : "unidirectional",
                           "id" : "urn:ogf:network:domain=ps.es.net:node=albu-sdn1:port=xe-0/1/0:link=xe-0/1/0.0"
                        }
                     ]
                  }, 
                ]
            }
         ],
         "id" : "urn:ogf:network:domain=ps.es.net"
      }
   ],
   "circuits" : [
      {
         "segment_ids" : [
            "urn:glif:es.net:es.net_circuit_es.net-1814_atoz",
            "urn:glif:es.net:es.net_circuit_es.net-1814_ztoa"
         ],
         "name" : "es.net-1814",
         "capacity" : 1000000000,
         "description" : "[PRODUCTION CIRCUIT] FNAL - TIFR, VLAN 2499",
         "segments" : [
            {
               "ports" : [
                  "urn:ogf:network:domain=es.net:node=fnal-mr2:port=xe-8/0/0.2499",
                  "urn:ogf:network:domain=es.net:node=fnal-mr2:port=xe-0/1/0",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-7/2/0",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-1/0/0",
                  "urn:ogf:network:domain=es.net:node=star-cr1:port=xe-1/0/0",
                  "urn:ogf:network:domain=es.net:node=star-cr1:port=xe-1/1/0.2499"
               ],
               "id" : "urn:glif:es.net:es.net_circuit_es.net-1814_atoz"
            },
            {
               "ports" : [
                  "urn:ogf:network:domain=es.net:node=star-cr1:port=xe-1/1/0.2499",
                  "urn:ogf:network:domain=es.net:node=star-cr1:port=xe-1/0/0",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-1/0/0",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-7/2/0",
                  "urn:ogf:network:domain=es.net:node=fnal-mr2:port=xe-0/1/0",
                  "urn:ogf:network:domain=es.net:node=fnal-mr2:port=xe-8/0/0.2499"
               ],
               "id" : "urn:glif:es.net:es.net_circuit_es.net-1814_ztoa"
            }
         ],
         "end" : "1575311160",
         "id" : "urn:glif:es.net:circuit_es.net-1814",
         "start" : "1259778180"
      },
      {
         "segment_ids" : [
            "urn:glif:es.net:es.net_circuit_es.net-1849_atoz",
            "urn:glif:es.net:es.net_circuit_es.net-1849_ztoa"
         ],
         "name" : "es.net-1849",
         "capacity" : 1000000000,
         "description" : "[PRODUCTION CIRCUIT] BNL-AGLT2 (UMich / Mich State), VLAN 3102",
         "segments" : [
            {
               "ports" : [
                  "urn:ogf:network:domain=es.net:node=bnl-mr3:port=xe-0/1/0.3102",
                  "urn:ogf:network:domain=es.net:node=bnl-mr3:port=xe-0/2/0",
                  "urn:ogf:network:domain=es.net:node=newy-sdn1:port=xe-7/1/0",
                  "urn:ogf:network:domain=es.net:node=newy-sdn1:port=xe-7/0/0",
                  "urn:ogf:network:domain=es.net:node=aofa-sdn1:port=xe-1/2/0",
                  "urn:ogf:network:domain=es.net:node=aofa-sdn1:port=xe-7/0/0",
                  "urn:ogf:network:domain=es.net:node=clev-sdn1:port=xe-0/1/0",
                  "urn:ogf:network:domain=es.net:node=clev-sdn1:port=xe-1/1/0",
                  "urn:ogf:network:domain=es.net:node=chic-sdn2:port=xe-2/2/0",
                  "urn:ogf:network:domain=es.net:node=chic-sdn2:port=xe-1/2/0",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-9/0/0",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-2/1/0.3102"
               ],
               "id" : "urn:glif:es.net:es.net_circuit_es.net-1849_atoz"
            },
            {
               "ports" : [
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-2/1/0.3102",
                  "urn:ogf:network:domain=es.net:node=star-sdn1:port=xe-9/0/0",
                  "urn:ogf:network:domain=es.net:node=chic-sdn2:port=xe-1/2/0",
                  "urn:ogf:network:domain=es.net:node=chic-sdn2:port=xe-2/2/0",
                  "urn:ogf:network:domain=es.net:node=clev-sdn1:port=xe-1/1/0",
                  "urn:ogf:network:domain=es.net:node=clev-sdn1:port=xe-0/1/0",
                  "urn:ogf:network:domain=es.net:node=aofa-sdn1:port=xe-7/0/0",
                  "urn:ogf:network:domain=es.net:node=aofa-sdn1:port=xe-1/2/0",
                  "urn:ogf:network:domain=es.net:node=newy-sdn1:port=xe-7/0/0",
                  "urn:ogf:network:domain=es.net:node=newy-sdn1:port=xe-7/1/0",
                  "urn:ogf:network:domain=es.net:node=bnl-mr3:port=xe-0/2/0",
                  "urn:ogf:network:domain=es.net:node=bnl-mr3:port=xe-0/1/0.3102"
               ],
               "id" : "urn:glif:es.net:es.net_circuit_es.net-1849_ztoa"
            }
         ],
         "end" : "1581789660",
         "id" : "urn:glif:es.net:circuit_es.net-1849",
         "start" : "1266256620"
      }
   ]
}