Floodlight REST API

Owned by Ryan Izard
Last updated: Mar 14, 2018 by Qing Wang (Deactivated)
7 min read

This page is for Floodlight v1.0 and up. If you are using Floodlight v0.9 or earlier or are using a copy of the master branch prior to December 30, 2014, please consider upgrading to Floodlight v1.1. If now isn't the time to upgrade, no worries, the pre-1.0 documentation can be found here.

Table of Contents

Getting Started

The REST API is the recommended way to develop separate, northbound applications that will utilize features exposed by Floodlight. If a feature does not exist that you would like to make accessible from a northbound application, you can create a REST API of your own.

While the functions available in this API are continuously evolving, several key functions are supported today and are documented in the table below. By default, the API is available at port 8080 of the controller. However, if you wish, you may tell Floodlight to use a different port or even use HTTPS if security is of concern.

Floodlight GUI

The Floodlight GUI is implemented using the REST API. Although the implementation details are beyond the scope of this documentation, information on how to access the GUI can be found here.

Using Curl to Access the REST API

An example REST call that retrieves data from Floodlight at IP address <controller-ip> is:

curl http://<controller-ip>:8080/wm/core/controller/switches/json

An example REST call that provides data to Floodlight at IP address <controller-ip> is:

curl http://<controller-ip>:8080/wm/core/switch/all/role/json -X POST -d '{"role":"MASTER"}'

The output from Floodlight's REST API is in JSON. Python can be used to parse the JSON string returned:

curl http://<controller-ip>:8080/wm/core/controller/switches/json | python -m json.tool

For each of the above examples, <controller-ip> should be replaced with the IP address or hostname of your controller.

Using Python to Access the REST API

Python can also be used to create a simple REST client for accessing the controller's REST API. An example Python script that leverages the Static Flow Pusher's REST API is shown below. Make sure to replace <insert_controller_ip> with your controller's IP address.

import httplib
import json
 
class StaticFlowPusher(object):
 
    def __init__(self, server):
        self.server = server
 
    def get(self, data):
        ret = self.rest_call({}, 'GET')
        return json.loads(ret[2])
 
    def set(self, data):
        ret = self.rest_call(data, 'POST')
        return ret[0] == 200
 
    def remove(self, objtype, data):
        ret = self.rest_call(data, 'DELETE')
        return ret[0] == 200
 
    def rest_call(self, data, action):
        path = '/wm/staticflowpusher/json'
        headers = {
            'Content-type': 'application/json',
            'Accept': 'application/json',
            }
        body = json.dumps(data)
        conn = httplib.HTTPConnection(self.server, 8080)
        conn.request(action, path, body, headers)
        response = conn.getresponse()
        ret = (response.status, response.reason, response.read())
        print ret
        conn.close()
        return ret
 
pusher = StaticFlowPusher('<insert_controller_ip')
 
flow1 = {
    'switch':"00:00:00:00:00:00:00:01",
    "name":"flow_mod_1",
    "cookie":"0",
    "priority":"32768",
    "in_port":"1",
    "active":"true",
    "actions":"output=flood"
    }
 
flow2 = {
    'switch':"00:00:00:00:00:00:00:01",
    "name":"flow_mod_2",
    "cookie":"0",
    "priority":"32768",
    "in_port":"2",
    "active":"true",
    "actions":"output=flood"
    }
 
pusher.set(flow1)
pusher.set(flow2)

Floodlight REST API


URI

Method

Description

Arguments

Controller Version

Controller

APIs









/wm/core/controller/switches/json

GET

List of all switch DPIDs connected to the controller

none

all

/wm/core/controller/summary/json

GET

Controller summary (# of Switches, # of Links, etc.)

none

all

/wm/core/module/all/json

GET

Retrieve all registered (but not loaded) modules.

none

all

/wm/core/module/loaded/json

GET

Retrieve all modules actively loaded by the module loader.

none

all

/wm/core/counter/<moduleName>/<counterTitle>/json

GET

List of counters per module, including switch counters.

moduleName: The name of the specific module for which to fetch counters. "OFSwitchManager" should be used for switch counters.
counterTitle: "all" or the name of the counter as defined in the module. Counters are defined in a hierarchical fashion and can be queried in groups by their common parent path in the counter hierarchy. 
For example, switch counters are defined at the root as "<dpid>:0x<aux-id>" or "00:00:00:00:00:00:00:01:0x01" where <dpid> is the switch DPID in hex-string form and <aux-id> is the OpenFlow connection ID in hexadecimal.
Among many counters in the hierarchy, all switches have specific "read" and "write" counters, which can be added to the counterTitle e.g. "00:00:00:00:00:00:00:01:0x01/read".

all

/wm/core/memory/json  

GET

Current controller memory usage

none

all

/wm/core/health/json

GET

Status/Health of REST API

none

all
/wm/core/version/jsonGETController version and namenoneall

/wm/core/system/uptime/json

GET

Controller uptime

none

all

/wm/core/storage/tables/json

GET

Tables present in Storage.

none

all

Role

(HA)

APIs

/wm/core/role/jsonGETRetrieve the current high availability role of the controller.Nonev1.0 and up

POSTSet the high availability role of the controller.

{"role":"<new-role>"}

new-role: "ACTIVE" or "STANDBY"

v1.0 and up

Role

(Switch)

APIs

/wm/core/switch/all/role/jsonGETRetrieve the roles of all the presently connected switches.
v1.1 and up

POSTSet the role of all presently connected switches.

{"role":"<new-role>"}

new-role: "MASTER", "SLAVE", or "EQUAL"

v1.2 and up
/wm/core/switch/<switchId>/role/jsonGETRetrieve the role of a particular connected switch.nonev1.2 and up

POSTSet the role of a particular connected switch.

{"role":"<role>"}

role: "MASTER", "SLAVE", or "EQUAL"

v1.2 and up

OpenFlow

Stats /

Multipart

APIs

/wm/core/switch/all/<statType>/json  

GET

Retrieve aggregate stats across all switches.
Some stats not supported by all all OpenFlow versions.
Meters untested.

statType: aggregate, desc, flow, group, group-desc, group-features, meter, meter-config, meter-features, port, port-desc, queue, table, features   

all

/wm/core/switch/<switchId>/<statType>/json  

GET

Retrieve per switch stats.
Some stats not supported by all all OpenFlow versions.
Meters untested.

switchId: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)  
statType: aggregate, desc, flow, group, group-desc, group-features, meter, meter-config, meter-features, port, port-desc, queue, table, features  

all

Statistics

APIs

 /wm/statistics/config/enable/json

POST

PUT

 Enable statistics collection

Send empty string

v1.2 and up
/wm/statistics/config/disable/json

POST

PUT

Disable statistics collectionSend empty stringv1.2 and up
/wm/statistics/bandwidth/<switchId>/<portId>/jsonGETFetch RX/TX bandwidth consumption

switchId: Valid Switch DPID as colon-delimited hex string or integer. Use "all" for all switches.

portId: Valid switch port number

v1.2 and up

Topology and Routing

APIs

  

 

/wm/topology/switchclusters/json

GET

List of all switch clusters connected to the controller.

none

v0.90 - v1.2

/wm/topology/external-links/json 

GET

Show "external" links, i.e., multi-hop links discovered by BDDP instead of LLDP packets 

none

all

/wm/topology/links/json 

GET

Show DIRECT and TUNNEL links discovered based on LLDP packets 

none

all

/wm/topology/route/<src-dpid>/<src-port>/<dst-dpid>/<dst-port>/json

GET

Get a route defined by switch DPIDs and switch ports from the source switch and port to the destination switch and port

src-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
src-port: Valid Switch Port Number
dst-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
dst-port: Valid Switch Port Number

v0.90 - v1.2
/wm/routing/path/<src-dpid>/<src-port>/<dst-dpid>/<dst-port>/jsonGETGet a path defined by switch DPIDs and the switch ports from the source switch and port to the destination switch and portsrc-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
src-port: Valid Switch Port Number
dst-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
dst-port: Valid Switch Port Number		master and up
/wm/routing/paths/<src-dpid>/<dst-dpid>/<num-paths>/jsonGETGet an ordered list of paths from the shortest to the longest path

src-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
dst-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)

num-paths: Max quantity of paths to locate

master and up
/wm/routing/paths/fast/<src-dpid>/<dst-dpid>/<num-paths>/jsonGETGet an ordered list of paths from the shortest to the longest path

src-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
dst-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)

num-paths: Max quantity of paths to locate

master and up
/wm/routing/paths/slow/<src-dpid>/<dst-dpid>/<num-paths>/jsonGETGet an ordered list of paths from the shortest to the longest path. Recompute paths if number requested is not cached

src-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)
dst-dpid: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX)

num-paths: Max quantity of paths to locate

master and up
/wm/routing/paths/force-recompute/jsonPOST/PUTRecompute and cache paths using configured metric and max-fast-pathsempty string, ''master and up
/wm/routing/paths/max-fast-paths/jsonGET/POST/PUTGet or set the max paths to attempt to cache upon path computatione.g. '{ "max_fast_paths" : "3" }'master and up
/wm/routing/metric/jsonGET/POST/PUTGet or set the metric to use when determining link cost

e.g. '{ "metric" : <metric> }', where <metric> is:

"hopcount"

"hopcount_avoid_tunnels"

"latency"

"utilization"

"link_speed"

master and up

Device

APIs

/wm/device/

GET

List of all devices tracked by the controller. This includes MACs, IPs, and attachment points

Passed as GET parameters: mac (colon-separated hex-encoded), ipv4 (dotted decimal), vlan, dpid attachment point DPID (colon-separated hex-encoded) and port the attachment point port.

all

Static

Entry

Pusher

APIs

/wm/staticflowpusher/json 

POST/DELETE

Add/Delete static flow 

HTTP POST data (add flow), HTTP DELETE (for deletion) 

all

/wm/staticflowpusher/list/<switch>/json 

GET

List static flows for a switch or all switches 

switch: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX) or "all" 

all

/wm/staticflowpusher/clear/<switch>/json 

GET

Clear static flows for a switch or all switches 

switch: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX) or "all" 

all

More information available on How to Use Static Flow Pusher API





Virtual

Network

Filter

APIs

/networkService/v1.1/tenants/<tenant>/networks/<network> 

PUT/POST/DELETE 

Creates a new virtual network. Name and ID are required, gateway is optional.

URI argument: tenant: Currently ignored. network: ID (not name) of the network 

HTTP data: {"network": { "gateway": "<IP>", "name": "<Name>" }} 
IP: Gateway IP in "1.1.1.1" format, can be null   
Name: Network name as string 

v0.91 and up

/networkService/v1.1/tenants/<tenant>/networks/<network>/ports/<port>/attachment

PUT/DELETE

Attaches a host to a virtual network.

URI argument: tenant: Currently ignored. network: ID (not name) of the network. port: Logical port name 

HTTP data: {"attachment": {"id": "<Network ID>", "mac": "<MAC>"}} 
Network ID: Network ID as string, the one assigned at create 
MAC: MAC address in "XX:XX:XX:XX:XX:XX" format 

v0.91 and up

/networkService/v1.1/tenants/<tenant>/networks

GET

Shows all networks and their gateway, ID, and hosts mac in json format. 

URI argument: tenant: Currently ignored. 

v0.91 and up

More information available on Virtual Network Filter REST API





Firewall

APIs

/wm/firewall/module/status/json 

GET

Query the status of the firewall.


all
/wm/firewall/module/enable/jsonPUTEnable the firewall.Send empty stringall
/wm/firewall/module/disable/jsonPUTDisable the firewall.Send empty stringall
/wm/firewall/module/subnet-mask/jsonGETGet the firewall's configured subnet mask.Noneall

POSTSet the subnet mask of the firewall."subnet-mask":"X.X.X.X", where X.X.X.X is a valid IPv4 subnet mask.all

/wm/firewall/rules/json  

GET/POST/DELETE

GET: None 
POST: {"<field 1>":"<value 1>", "<field 2>":"<value 2>", ...} 
DELETE: {"<ruleid>":"<int>"}

List all existing rules in json format 
Create new firewall rule 
Delete a rule by ruleid 
"field":"value" pairs below in any order and combination:  
"switchid":"<xx:xx:xx:xx:xx:xx:xx:xx>", "src-inport":"<short>",   
"src-mac": "<xx:xx:xx:xx:xx:xx>", "dst-mac": "<xx:xx:xx:xx:xx:xx>",   
"dl-type": "<ARP or IPv4>", "src-ip": "<A.B.C.D/M>", "dst-ip": "<A.B.C.D/M>",   
"nw-proto": "<TCP or UDP or ICMP>", "tp-src": "<short>", "tp-dst": "<short>",   
"priority": "<int>", "action": "<ALLOW or DENY>"  
"ruleid": "<int>"  

all

More information available on Firewall REST API





Access

Control

List

APIs



   		/wm/acl/rules/jsonPOST

Add a rule

'{"<key>":"<value>", "<key>":"<value>", ...}'

<key>:value> pairs can be any of:

"nw-proto" : "any valid network protocol number"

"src-ip" : "ip/mask"

"dst-ip" : "ip/mask"

"tp-dst" : "any valid transport port number"

"action" : "ALLOW | DENY"

v1.1 and up
/wm/acl/rules/jsonDELETE

Delete a rule.

{"ruleid":"<rule>"}

rule: The ID of the rule as returned when it was addedv1.1 and up
/wm/acl/rules/jsonGETList all rulesnonev1.1 and up
/wm/acl/clear/jsonGETDelete all rulesnonev1.1 and up
More information available on ACL (Access Control List) REST API



Controller Performance

APIs

/wm/performance/jsonGETGet controller performance monitoring status nonev0.9 and up
/wm/performance/enable/jsonPOSTEnable controller performance monitoringnonev0.9 and up
/wm/performance/disable/jsonPOSTDisable controller performance monitoringnonev0.9 and up
/wm/performance/reset/jsonPOSTReset controller performance monitoringnonev0.9 and up
/wm/performance/data/jsonGETRetrieve the average packet-in processing time of the controllernonev0.9 and up

Module REST API Documentation