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.

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/json	GET	Controller version and name	none	all
	/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/json	GET	Retrieve the current high availability role of the controller.	None	v1.0 and up
Role (HA) APIs		POST	Set 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/json	GET	Retrieve the roles of all the presently connected switches.		v1.1 and up
		POST	Set 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/json	GET	Retrieve the role of a particular connected switch.	none	v1.2 and up
		POST	Set 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
OpenFlow Stats / Multipart APIs	/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 collection	Send empty string	v1.2 and up
	/wm/statistics/bandwidth/<switchId>/<portId>/json	GET	Fetch 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>/json	GET	Get a path defined by switch DPIDs and the 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	master and up
	/wm/routing/paths/<src-dpid>/<dst-dpid>/<num-paths>/json	GET	Get 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>/json	GET	Get 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>/json	GET	Get 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/json	POST/PUT	Recompute and cache paths using configured metric and max-fast-paths	empty string, ''	master and up
	/wm/routing/paths/max-fast-paths/json	GET/POST/PUT	Get or set the max paths to attempt to cache upon path computation	e.g. '{ "max_fast_paths" : "3" }'	master and up
	/wm/routing/metric/json	GET/POST/PUT	Get 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/json	PUT	Enable the firewall.	Send empty string	all
	/wm/firewall/module/disable/json	PUT	Disable the firewall.	Send empty string	all
	/wm/firewall/module/subnet-mask/json	GET	Get the firewall's configured subnet mask.	None	all
		POST	Set 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/json	POST	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/json	DELETE	Delete a rule. {"ruleid":"<rule>"}	rule: The ID of the rule as returned when it was added	v1.1 and up
	/wm/acl/rules/json	GET	List all rules	none	v1.1 and up
	/wm/acl/clear/json	GET	Delete all rules	none	v1.1 and up
	More information available on ACL (Access Control List) REST API
Controller Performance APIs	/wm/performance/json	GET	Get controller performance monitoring status	none	v0.9 and up
	/wm/performance/enable/json	POST	Enable controller performance monitoring	none	v0.9 and up
	/wm/performance/disable/json	POST	Disable controller performance monitoring	none	v0.9 and up
	/wm/performance/reset/json	POST	Reset controller performance monitoring	none	v0.9 and up
	/wm/performance/data/json	GET	Retrieve the average packet-in processing time of the controller	none	v0.9 and up

Browser not supported