How to Write a REST Application

Writing a REST application is one of the quickest and perhaps easiest way for most people to start harnessing the power of an OpenFlow network.  

To write a REST application in any programming language of your choice, you will typically go through the following steps:

1. Determine the "network services/information" your application needs
2. Check out the Floodlight REST API pre-v1.0 page to find the REST APIs that provide these services
   1. If its found, take note of the REST API syntax, input arguments, and available options
   2. If its not found, the services/information may still be available in Floodlight but has not been exposed through a REST API yet.  In this case, you should: 1) email the floodlight-dev list to discuss what you need and 2) after consulting with the developer community, you may implement and contribute a REST API to expose the service.  (The Floodlight team at Big Switch is drafting a proposed syntax and set of REST APIs for Floodlight and will soon be available for community suggestions)
   3. if its not found and the service simply does not exist in Floodlight at this time, you should 1) 1) email the floodlight-dev list to discuss what you need and 2) after consulting with the developer community,based on whether it is more suitable as a controller module or an application module, you may implement and contribute the Java module.
3. With all needed REST API calls, design and compose your application.
4. Implement tests for it and contribute your application and/or added service modules/APIs back to Floodlight. 

An example of this can be found from the python Circuit Pusher application released with Floodlight under the floodlight/apps directory. 

The Circuit Pusher example demonstrates how to create a static single path circuit between two IP hosts A and B in a single OpenFlow cluster.  Following the design approach above:

1. The needed network services/information:
   • The "attachment points" for hosts A and B (the data entity used to represent physical location of a host based on the (switch, port) it is connected to;
   • The "route" between A and B's attachment points;
   • Service to install a circuit for traffic from/to A and B on all switches on the A-B route. 
2. From the Floodlight REST API pre-v1.0s:
   • GET with /wm/device/ with GET parameters allows us to find out the attachment point info for any device provided its attribute (such as IP address)
   • GET with /wm/topology/route/<switchIdA>/<portA>/<switchIdB>/<portB>/json allows us to find out a route, if one exists, between A and B based on attachment points (switch, port).
   • POST with /wm/staticflowentrypusher/json with POST parameters allows us to install one flow entry on one specified switch
3. Application design: (source)
   • We decided to use python for our application
   • We decided to use os.popen to send out curl commands for the REST API calls
   • We figure out the /wm/device syntax and parse the attachment point switch port for host A and host B
   • We figure out that /wm/topology/route returns switch port pairs (switch X port M to switch X port N) of which each can be use to form a flow entry
   • For each switch port pair, we will install four flow entries on switch X using /wm/staticflowentrypusher/json:
     • ether-type '0x0800', port M ? N
     • ether-type '0x0806', port M ? N
     • ether-type '0x0800', port N ? M
     • ether-type '0x0806', port N ? M
   • If everything works as expected, we are done! (the core feature at least ... do a ping or iperf between A and B to see it work)
   • To wrap up the design, we decided two added features would be useful:
     • option to remove flows, since these are "static" flows that by definition never times out!
     • ability to remember flows already pushed. We decided to use a simple text file to store the flows for this example.
4. Complete integration test and submit code to floodlight!
   • See How to Write Tests
   • See How to Submit a Patch