Skip to main content

Networking API Reference

The Networking API provides comprehensive network management capabilities through SDN controller integration, supporting both Ryu and ONOS controllers for dynamic traffic management, QoS enforcement, and network topology control.

Base URL​

http://localhost:8181/api/v1  # ONOS Controller
http://localhost:8080/api/v1  # Ryu Controller

Authentication​

Include API key in the Authorization header:

Authorization: Bearer networking_api_key_here

Network Topology​

Get Network Topology​

GET /topology

Response:

{
  "topology": {
    "switches": [
      {
        "id": "of:0000000000000001",
        "type": "OpenFlow",
        "version": "1.3",
        "manufacturer": "Open vSwitch",
        "hardware": "2.15.0",
        "software": "2.15.0",
        "ports": [
          {
            "number": 1,
            "name": "eth1",
            "status": "enabled",
            "speed": "1Gbps",
            "duplex": "full"
          }
        ],
        "flows_count": 15,
        "status": "connected",
        "last_seen": "2024-01-15T11:30:00Z"
      }
    ],
    "hosts": [
      {
        "id": "00:00:00:00:00:01/None",
        "mac": "00:00:00:00:00:01",
        "ip": "192.168.141.10",
        "location": {
          "switch": "of:0000000000000001",
          "port": 1
        },
        "type": "fl_client",
        "status": "active",
        "last_seen": "2024-01-15T11:29:30Z"
      }
    ],
    "links": [
      {
        "id": "link_001",
        "source": {
          "switch": "of:0000000000000001",
          "port": 2
        },
        "destination": {
          "switch": "of:0000000000000002",
          "port": 1
        },
        "bandwidth": "1Gbps",
        "latency": "2ms",
        "utilization": 45.2,
        "status": "active"
      }
    ]
  },
  "statistics": {
    "total_switches": 3,
    "total_hosts": 8,
    "total_links": 4,
    "total_flows": 45,
    "network_utilization": 38.5
  }
}

Get Switch Details​

GET /switches/{switch_id}

Response:

{
  "switch": {
    "id": "of:0000000000000001",
    "type": "OpenFlow",
    "version": "1.3",
    "manufacturer": "Open vSwitch",
    "connection": {
      "status": "connected",
      "ip": "192.168.141.100",
      "port": 6653,
      "connected_since": "2024-01-15T09:00:00Z"
    },
    "ports": [
      {
        "number": 1,
        "name": "eth1",
        "status": "enabled",
        "statistics": {
          "rx_packets": 15678,
          "tx_packets": 14892,
          "rx_bytes": 2345678,
          "tx_bytes": 2198765,
          "errors": 0,
          "drops": 2
        }
      }
    ],
    "flows": [
      {
        "id": "flow_001",
        "priority": 100,
        "match": {
          "in_port": 1,
          "eth_type": "0x0800",
          "ip_proto": 6,
          "tcp_dst": 8080
        },
        "actions": [
          {
            "type": "set_queue",
            "queue_id": 1
          },
          {
            "type": "output",
            "port": 2
          }
        ],
        "statistics": {
          "packet_count": 1256,
          "byte_count": 156789,
          "duration": "00:15:30"
        }
      }
    ],
    "queues": [
      {
        "id": 1,
        "port": 2,
        "properties": {
          "min_rate": "10Mbps",
          "max_rate": "100Mbps"
        }
      }
    ]
  }
}

Get Network Statistics​

GET /statistics

Query Parameters:

  • metric: bandwidth, latency, packet_loss, flow_count
  • granularity: 1m, 5m, 1h
  • from: Start time (ISO 8601)
  • to: End time (ISO 8601)

Response:

{
  "statistics": {
    "bandwidth": {
      "total_capacity": "10Gbps",
      "current_utilization": "3.2Gbps",
      "utilization_percentage": 32.0,
      "peak_utilization": "4.8Gbps",
      "peak_time": "2024-01-15T10:45:00Z"
    },
    "latency": {
      "average": "15ms",
      "minimum": "2ms",
      "maximum": "45ms",
      "p95": "35ms"
    },
    "packet_loss": {
      "rate": 0.001,
      "total_dropped": 156,
      "total_transmitted": 156000
    },
    "flows": {
      "total_active": 45,
      "new_flows": 12,
      "expired_flows": 8,
      "average_duration": "00:08:30"
    }
  },
  "per_switch": [
    {
      "switch_id": "of:0000000000000001",
      "flows": 15,
      "utilization": 25.5,
      "status": "healthy"
    }
  ]
}

Flow Management​

Install Flow Rule​

POST /flows
Content-Type: application/json

Request Body:

{
  "switch_id": "of:0000000000000001",
  "priority": 100,
  "timeout": {
    "idle": 30,
    "hard": 300
  },
  "match": {
    "in_port": 1,
    "eth_type": "0x0800",
    "ip_proto": 6,
    "ipv4_src": "192.168.141.10/32",
    "ipv4_dst": "192.168.141.20/32",
    "tcp_dst": 8080
  },
  "actions": [
    {
      "type": "set_queue",
      "queue_id": 1
    },
    {
      "type": "set_field",
      "field": "ip_dscp",
      "value": "46"
    },
    {
      "type": "output",
      "port": 2
    }
  ],
  "metadata": {
    "experiment_id": "exp_001",
    "client_id": "client_003",
    "traffic_type": "fl_communication"
  }
}

Response:

{
  "flow": {
    "id": "flow_new_001",
    "switch_id": "of:0000000000000001",
    "status": "installed",
    "installation_time": "2024-01-15T11:30:00Z",
    "cookie": "0x123456789abcdef0"
  }
}

List Flow Rules​

GET /flows

Query Parameters:

  • switch_id: Filter by switch
  • priority: Filter by priority
  • status: active, expired, pending
  • experiment_id: Filter by experiment

Response:

{
  "flows": [
    {
      "id": "flow_001",
      "switch_id": "of:0000000000000001",
      "priority": 100,
      "status": "active",
      "match": {
        "in_port": 1,
        "eth_type": "0x0800",
        "tcp_dst": 8080
      },
      "actions": [
        {
          "type": "set_queue",
          "queue_id": 1
        },
        {
          "type": "output",
          "port": 2
        }
      ],
      "statistics": {
        "packet_count": 1256,
        "byte_count": 156789,
        "duration": "00:15:30",
        "packets_per_second": 1.4,
        "bits_per_second": "8.4Kbps"
      },
      "installed_at": "2024-01-15T11:15:00Z",
      "last_matched": "2024-01-15T11:29:45Z"
    }
  ],
  "total": 1
}

Update Flow Rule​

PUT /flows/{flow_id}
Content-Type: application/json

Request Body:

{
  "priority": 150,
  "actions": [
    {
      "type": "set_queue",
      "queue_id": 2
    },
    {
      "type": "output",
      "port": 2
    }
  ]
}

Delete Flow Rule​

DELETE /flows/{flow_id}

Response:

{
  "status": "deleted",
  "flow_id": "flow_001",
  "timestamp": "2024-01-15T11:35:00Z"
}

Quality of Service (QoS)​

Configure QoS Queue​

POST /qos/queues
Content-Type: application/json

Request Body:

{
  "switch_id": "of:0000000000000001",
  "port": 2,
  "queue_id": 1,
  "properties": {
    "min_rate": "10Mbps",
    "max_rate": "100Mbps",
    "burst": "10MB",
    "priority": "high"
  },
  "dscp_mapping": [46, 34, 26],
  "description": "FL communication priority queue"
}

Response:

{
  "queue": {
    "id": 1,
    "switch_id": "of:0000000000000001",
    "port": 2,
    "status": "configured",
    "properties": {
      "min_rate": "10Mbps",
      "max_rate": "100Mbps",
      "burst": "10MB"
    },
    "statistics": {
      "enqueued_packets": 0,
      "dropped_packets": 0,
      "current_rate": "0bps"
    }
  }
}

Get QoS Configuration​

GET /qos/queues

Query Parameters:

  • switch_id: Filter by switch
  • port: Filter by port

Response:

{
  "queues": [
    {
      "id": 1,
      "switch_id": "of:0000000000000001",
      "port": 2,
      "properties": {
        "min_rate": "10Mbps",
        "max_rate": "100Mbps"
      },
      "statistics": {
        "enqueued_packets": 1256,
        "dropped_packets": 12,
        "current_rate": "25Mbps",
        "utilization": 25.0
      }
    }
  ]
}

Apply Traffic Shaping​

POST /qos/shaping
Content-Type: application/json

Request Body:

{
  "switch_id": "of:0000000000000001",
  "port": 2,
  "policy": {
    "type": "token_bucket",
    "rate": "50Mbps",
    "burst": "5MB"
  },
  "filters": [
    {
      "match": {
        "ip_dscp": 46
      },
      "action": "allow"
    },
    {
      "match": {
        "ip_dscp": 0
      },
      "action": "limit",
      "rate": "10Mbps"
    }
  ]
}

Path Management​

Calculate Optimal Path​

POST /paths/calculate
Content-Type: application/json

Request Body:

{
  "source": {
    "host": "00:00:00:00:00:01",
    "ip": "192.168.141.10"
  },
  "destination": {
    "host": "00:00:00:00:00:02",
    "ip": "192.168.141.20"
  },
  "constraints": {
    "bandwidth": "20Mbps",
    "latency": "50ms",
    "avoid_switches": ["of:0000000000000003"]
  },
  "optimization": "latency" // "bandwidth", "load_balance", "shortest"
}

Response:

{
  "path": {
    "id": "path_001",
    "source": "192.168.141.10",
    "destination": "192.168.141.20",
    "hops": [
      {
        "switch": "of:0000000000000001",
        "in_port": 1,
        "out_port": 2
      },
      {
        "switch": "of:0000000000000002",
        "in_port": 1,
        "out_port": 2
      }
    ],
    "metrics": {
      "total_latency": "15ms",
      "available_bandwidth": "800Mbps",
      "hop_count": 2,
      "reliability": 0.99
    },
    "backup_paths": [
      {
        "hops": 3,
        "latency": "25ms",
        "bandwidth": "600Mbps"
      }
    ]
  }
}

Install Path​

POST /paths/{path_id}/install
Content-Type: application/json

Request Body:

{
  "priority": 100,
  "qos_class": "high",
  "backup_enabled": true,
  "monitoring": {
    "enabled": true,
    "interval": "30s",
    "alerts": {
      "latency_threshold": "100ms",
      "packet_loss_threshold": 0.01
    }
  }
}

Get Path Status​

GET /paths/{path_id}

Response:

{
  "path": {
    "id": "path_001",
    "status": "active",
    "installed_at": "2024-01-15T11:30:00Z",
    "flows_installed": 2,
    "current_metrics": {
      "latency": "12ms",
      "packet_loss": 0.0005,
      "throughput": "45Mbps",
      "utilization": 0.056
    },
    "alerts": [],
    "backup_status": "standby"
  }
}

Network Monitoring​

Real-time Metrics​

GET /monitoring/realtime

Query Parameters:

  • switches: Comma-separated switch IDs
  • metrics: bandwidth,latency,packet_loss,flows
  • interval: Update interval in seconds

Response:

{
  "timestamp": "2024-01-15T11:35:00Z",
  "switches": [
    {
      "id": "of:0000000000000001",
      "metrics": {
        "cpu_usage": 25.5,
        "memory_usage": 45.2,
        "port_utilization": {
          "1": 12.5,
          "2": 34.8
        },
        "flow_table_usage": 0.33,
        "packet_rate": 1250,
        "error_rate": 0.001
      }
    }
  ],
  "network_wide": {
    "total_bandwidth": "10Gbps",
    "utilized_bandwidth": "3.2Gbps",
    "average_latency": "15ms",
    "packet_loss_rate": 0.0008,
    "active_flows": 45
  }
}

WebSocket Monitoring​

const ws = new WebSocket('ws://localhost:8181/ws/monitoring');

ws.onopen = function() {
    ws.send(JSON.stringify({
        action: 'subscribe',
        events: ['topology_change', 'link_failure', 'flow_stats'],
        switches: ['of:0000000000000001']
    }));
};

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    
    switch(data.type) {
        case 'topology_change':
            console.log('Topology changed:', data.details);
            break;
        case 'link_failure':
            console.log('Link failure detected:', data.link);
            break;
        case 'flow_stats':
            console.log('Flow statistics:', data.statistics);
            break;
    }
};

Historical Analytics​

GET /analytics/historical

Query Parameters:

  • metric: bandwidth, latency, packet_loss, topology_changes
  • from: Start time (ISO 8601)
  • to: End time (ISO 8601)
  • granularity: 1m, 5m, 1h, 1d
  • aggregation: avg, max, min, sum

Response:

{
  "metric": "bandwidth",
  "time_range": {
    "from": "2024-01-15T10:00:00Z",
    "to": "2024-01-15T11:00:00Z"
  },
  "granularity": "5m",
  "data_points": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "total_bandwidth": "10Gbps",
      "utilized_bandwidth": "2.8Gbps",
      "utilization_percentage": 28.0
    },
    {
      "timestamp": "2024-01-15T10:05:00Z",
      "total_bandwidth": "10Gbps",
      "utilized_bandwidth": "3.2Gbps",
      "utilization_percentage": 32.0
    }
  ],
  "summary": {
    "avg_utilization": 30.5,
    "peak_utilization": 42.8,
    "peak_time": "2024-01-15T10:35:00Z"
  }
}

GNS3 Integration​

Get GNS3 Projects​

GET /gns3/projects

Response:

{
  "projects": [
    {
      "id": "gns3_proj_001",
      "name": "FLOPY-NET Testbed",
      "status": "opened",
      "topology": {
        "nodes": 8,
        "links": 12,
        "switches": 3,
        "hosts": 5
      },
      "created_at": "2024-01-15T09:00:00Z",
      "last_modified": "2024-01-15T11:00:00Z"
    }
  ]
}

Control GNS3 Node​

POST /gns3/nodes/{node_id}/control
Content-Type: application/json

Request Body:

{
  "action": "start", // "start", "stop", "suspend", "reload"
  "wait_for_ready": true,
  "timeout": 30
}

Inject Network Conditions​

POST /gns3/conditions/inject
Content-Type: application/json

Request Body:

{
  "target": {
    "type": "link",
    "id": "link_001"
  },
  "conditions": {
    "latency": "100ms",
    "jitter": "10ms",
    "packet_loss": 0.05,
    "bandwidth_limit": "1Mbps"
  },
  "duration": "5m",
  "description": "Simulate network congestion during FL training"
}

Error Handling​

Flow Installation Error​

{
  "error": {
    "code": "FLOW_INSTALLATION_FAILED",
    "message": "Failed to install flow rule",
    "details": {
      "switch_id": "of:0000000000000001",
      "reason": "Table full",
      "max_flows": 1000,
      "current_flows": 1000
    }
  }
}

Controller Connection Error​

{
  "error": {
    "code": "CONTROLLER_UNREACHABLE",
    "message": "SDN controller is not responding",
    "details": {
      "controller_type": "onos",
      "endpoint": "http://localhost:8181",
      "last_successful_connection": "2024-01-15T11:20:00Z",
      "retry_available": true
    }
  }
}

SDK Examples​

Python SDK​

from flopy_net_client import NetworkingClient

# Initialize client
network = NetworkingClient(
    base_url="http://localhost:8181/api/v1",
    api_key="networking_api_key"
)

# Get current topology
topology = network.get_topology()
print(f"Network has {len(topology.switches)} switches")

# Install QoS flow for FL traffic
flow = network.install_flow({
    "switch_id": "of:0000000000000001",
    "priority": 100,
    "match": {
        "tcp_dst": 8080,
        "ip_dscp": 46
    },
    "actions": [
        {"type": "set_queue", "queue_id": 1},
        {"type": "output", "port": 2}
    ]
})

# Monitor network metrics
for metrics in network.stream_metrics(['bandwidth', 'latency']):
    print(f"Network utilization: {metrics.utilization}%")
    if metrics.utilization > 80:
        print("High network utilization detected!")

JavaScript SDK​

import { NetworkingClient } from 'flopy-net-client';

const network = new NetworkingClient({
    baseUrl: 'http://localhost:8181/api/v1',
    apiKey: 'networking_api_key'
});

// Calculate and install optimal path
const path = await network.calculatePath({
    source: '192.168.141.10',
    destination: '192.168.141.20',
    constraints: {
        bandwidth: '20Mbps',
        latency: '50ms'
    }
});

await network.installPath(path.id, {
    priority: 100,
    qos_class: 'high',
    backup_enabled: true
});

// Real-time topology monitoring  
const monitor = network.createTopologyMonitor();
monitor.on('switch_connected', (switch_info) => {
    console.log('Switch ' + switch_info.id + ' connected');
});

monitor.on('link_failure', (link_info) => {
    console.log('Link failure: ' + link_info.id);
    // Trigger failover logic
});