Floodlight REST API
- Ryan Izard
- Qing Wang (Deactivated)
- Ryan Izard
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. | 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 |
| 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. | 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. | switchId: Valid Switch DPID (XX:XX:XX:XX:XX:XX:XX:XX) | 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) | 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) 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) 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) 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 | 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 | 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 | List all existing rules in json format | 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 |