Skip to content
This repository has been archived by the owner on Nov 13, 2023. It is now read-only.

API Changes

Jump to bottom
mssumanth edited this page Aug 4, 2013 · 38 revisions

Table of Contents

READ BELOW

Due to a bug in the github page rendering you can find this page in PDF format here.

API Changes

We are transitioning the API to JSON from XMLRPC. The API syntax may change in some areas and therefore this document is intended to details these changes. These changes will be introduced as of FlowVisor 1.0.

The XMLRPC API will remain as is but in a deprecated state, eventually it will be removed. So FlowVisor users are advised to transition any of their dependencies on the API to the JSON interface.

We are introducing two APIs with the JSON RPC API. The first will be used to configure the FlowVisor while the other one will be used to obtain monitoring information.

JSON-RPC API

The API will be implemented according to the JSON RPC 2.0 Spec found at http://www.jsonrpc.org/specification

Each request will be make with the following wire protocol: 

{
 "id":<string>,
 "method":<method-name>,
 "params":<input>,
 "jsonrpc":"2.0"
}

The params field is specified in the input column of the tables below.

Each reply will be make with the following wire protocol: 

{
 "id":<string>,
 "result":<output>,
 "error": {
            "code" : <error-code>,
            "msg" : <msg>,
            "data" : <data>
          },
 "jsonrpc":"2.0"
}

The error field will only be present in case of an error. The result field will only be present in case of success. The result field is specified in the output column of the below tables.

Error codes

code message meaning
-32700 Parse error Invalid JSON was received by the server.
-32600 Invalid Request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.

Configuration API

Command Name Input Output
[POST]
add-slice
 
{ 
 "slice-name" : <name>, 
 "controller-url" : <pseudo-url>, 
 "admin-contact" : <email>, 
 "password" : <password>, 
 "drop-policy" : "exact|rule", 
          OPTIONAL DEFAULT "exact" 
 "recv-lldp" : <boolean>, 
          OPTIONAL DEFAULT false
 "flowmod-limit" : <number>, 
        OPTIONAL DEFAULT -1
 "rate-limit" : <number>,
        OPTIONAL DEFAULT -1
 "admin-status" : <boolean>
        OPTIONAL DEFAULT true
} 

 <boolean>
[POST]
list-slices
 
None

 [ 
  { 
    "slice-name" : <name>,
    "admin-status" <boolean>
  }
 ]
[POST]
update-slice
 
{
 "slice-name" : <name>,
 "controller-host" : <hostname>, 
        OPTIONAL
 "controller-port" : <port-number>,
        OPTIONAL
 "admin-contact" : <email>,
 "drop-policy" : "exact|rule", 
        OPTIONAL
 "recv-lldp" : <boolean>, 
        OPTIONAL
 "flowmod-limit" : <number>, 
        OPTIONAL
 "rate-limit" : <number>,
        OPTIONAL
 "admin-status" : <boolean>
        OPTIONAL
}

  <boolean>
[POST]
remove-slice
 
{
 "slice-name" : <name>
}

  <boolean>
[POST]
update-slice-password
 
{ 
 "slice-name" : <name>, 
 "password" : <password> 
}

  <boolean>
[POST]
list-flowspace
 
{
 "slice-name" : <name> 
    OPTIONAL
 "show-disabled" : <boolean>
    OPTIONAL 
}

 [ <flowspace-entries> ]
[POST]
remove-flowspace
 
[
 <flowspace-name>
]

  <boolean>
[POST]
add-flowspace
 
[
 { 
   "name" : <string>,
   "dpid" : <dpid>,
   "priority" : <number>, 
   "match" : <match-struct>,
   "queues" : [ <queue_id> ],
            OPTIONAL
   "force-enqueue" : <queue_id>,
            OPTIONAL
   "slice-action" :
   [
    { 
      "slice-name" : <name> ", 
      "permission" : <perm-value> 
    }
   ]
 }
]

  <Integer - index Id>
[POST]
update-flowspace
 
[
 { 
   "name" : <string>
   "dpid" : <dpid>, 
           OPTIONAL
   "priority" : <number>, 
           OPTIONAL
   "match" : <match-struct>, 
           OPTIONAL
   "queues" : [ <queue_id> ],
            OPTIONAL
   "force-enqueue" : <queue_id>,
            OPTIONAL
   "slice-action" : 
   [
    { 
      "slice-name" : <name> ", 
      "permission" : <perm-value> 
    } OPTIONAL
   ]
 }
]

  <Integer - index Id>
[POST]
list-fs-status
 
{
  "fs-id" : <flowspace-request-id>
}

# SUCCESS = Great!
# PENDING = In process
# UNKNOWN = Unknown id
# err_msg = an error msg
   <string>
[POST]
list-version
 
None

{
  "flowvisor-version" : <version>,
  "db-version" : <version>
}
[POST]
set-config
 
# Default values here represent
# values at FV initialisation
# and not the default values 
# if parameters are omitted.
# -1 == no limit
{
 "flood-perm" : 
  {
   "slice-name" : <name>,
   "dpid" : <dpid> OPTIONAL
  },
    OPTIONAL DEFAULT NONE
 "flowmod-limit" :
  {
   "slice-name" : <name>,
   "dpid" : <dpid>,
   "limit" : <number>
  },
    OPTIONAL DEFAULT -1
  "track-flows" : <boolean>, 
    OPTIONAL DEFAULT false
 "stats-desc" : <boolean>, 
    OPTIONAL DEFAULT false
 "enable-topo-ctrl" : <boolean>,
    OPTIONAL DEFAULT false
 "flow-stats-cache" : <number>
    OPTIONAL DEFAULT 30 (seconds)
}

  <boolean>
[POST]
get-config
 
{
 "slice-name" : <name>, OPTIONAL
 "dpid" : <dpid>, OPTIONAL
}

# if slice and/or dpid
# specified then results
# will only include this
# slice or dpid, if applicable.
{
  "flood-perm" : 
   [
    {
     "slice-name" : <name>,
     "dpid" : <dpid>
    }
   ],
  "flowmod-limit" : 
    { <slice-name> : 
     {
      <dpid> : <limit>
     }
    }
   ,
  "track-flows" : <boolean>, 
  "stats-desc" : <boolean>, 
  "enable-topo-ctrl" : <boolean>,
  "flow-stats-cache" : <number>, 
}
[POST]
save-config
 
None

# returns the config as a 
# single text blob
  <text>

Monitoring API

Command Name Input Output
[POST]
list-slice-info
 
{
 "slice-name" : <name>
}

# msg field to be used 
# for ad-hoc communication
{ 
  "slice-name" : <name>,
  "controller-url" : <pseudo-url>, 
  "admin-contact" : <email>, 
  "drop-policy" : "exact|rule",
  "recv-lldp" : <boolean>,
  "current-rate" : "msgs-per-sec",
  "current-flowmod-usage" : <number>,
  "msg" : <string> 
}
[POST]
list-datapaths
 
None

[ <dpid>  ]
[POST]
list-links
 
None

[
  {
    "srcDpid" : <dpid>,
    "srcPort" : <port-no>,
    "dstDpid" : <dpid>,
    "dstPort" : <port-no>
  }
]
[POST]
list-datapath-info
 
{
  "dpid" : <dpid>
}

{
  "dpid" : <dpid>,
  "num-ports" : <number>,
  "port-list" : [ <port-no> ],
  "port-names" : [ <port-names> ],
  "connection" : <connection-id>,
  "current-flowmod-usage" : 
       {
         <slicename> : <limit>,
         <slicename> : <limit>,
         .
         .
         .
         <slicename> : <limit>
       } 
}
[POST]
list-slice-stats
 
{
  "slice-name" : <name>
}

#There may be may sender-names, hence
#the map
{
  "tx" : { 
           <sender-name> : {
             <msg-type-name> : <value>,
             <msg-type-name> : <value>,
             .
             .
             .
             <msg-type-name> : <value>
           }
         },
  "rx" : { 
           <sender-name> : {
             <msg-type-name> : <value>,
             <msg-type-name> : <value>,
             .
             .
             .
             <msg-type-name> : <value>
           }
         },
  "drop" : { 
           <sender-name> : {
             <msg-type-name> : <value>,
             <msg-type-name> : <value>,
             .
             .
             .
             <msg-type-name> : <value>
           }
         }
}
[POST]
list-datapath-stats
 
{
  "dpid" : <dpid>
}

#There may be may sender-names, hence
#the map
{
  "tx" : { 
           <sender-name> : {
             <msg-type-name> : <value>,
             <msg-type-name> : <value>,
             .
             .
             .
             <msg-type-name> : <value>
           }
         },
  "rx" : { 
           <sender-name> : {
             <msg-type-name> : <value>,
             <msg-type-name> : <value>,
             .
             .
             .
             <msg-type-name> : <value>
           }
         },
  "drop" : { 
           <sender-name> : {
             <msg-type-name> : <value>,
             <msg-type-name> : <value>,
             .
             .
             .
             <msg-type-name> : <value>
           }
         }
}
[POST]
list-fv-health
 
None

{
  "average-delay" : <millisec-delay>,
  "instant-delay" : <millisec-delay>, 
  "active-db-sessions" : <number>,
  "idle-db-sessions" : <number>
}
[POST]
list-slice-health
 
{
  "slice-name" : <name>
}

{
  "is-connected" : <boolean>,
  "connect-drop-count" : <number>, 
  "fs-entries" : <number>,
  "connected-dpids" : [ <dpid> ]
}
[POST]
register-event-callback
 
# event-type is:
#   DEVICE_CONNECTED  
#   SLICE_CONNECTED
#   SLICE_DISCONNECTED
{
  "url" : <url>,
  "method" : <method_name>,
  "event-type" : <ev_type>,
  "name" : <string>
}

# event-type is:
# FLOWTABLE_CALLBACK
# Eg.  ./fvctl.py register-event-callback http://127.0.0.1:8000 
# foo FLOWTABLE_CALLBACK alice -d 3
# dpid is optional, if not specified with the -d option, 
# the api will consider it as all dpids.
{
  "url" : <url>,
  "method" : <method_name>,
  "event-type" : <ev_type>,
  "name" : <string>
  "dpid" : <dpid>
}

# event-type is:
# DEVICE_CONNECTED  
# SLICE_CONNECTED
# SLICE_DISCONNECTED
<boolean>  

# event-type is:
# FLOWTABLE_CALLBACK
# Body of reply to OFPST_FLOW request. 
struct ofp_flow_stats {
    length; <int>
    table_id; <int>
    #Match
    struct ofp_match match; <map of maps>
    duration_sec; <int>
    duration_nsec; <int>
    priority; <int>
    idle_timeout; <int>
    hard_timeout; <int>
    cookie; <int>
    packet_count; <int>
    byte_count; <int>
    # Actions
    struct ofp_action_header actions; 
    <map with a list which contains maps of a map>
};
[POST]
unregister-event-callback
 
# event-type is:
#   DEVICE_CONNECTED  
#   SLICE_CONNECTED
#   SLICE_DISCONNECTED
{
  "method" : <method_name>,
  "event-type" : <ev_type>,
  "name" : <string>
}

# event-type is:
# FLOWTABLE_CALLBACK  
# Eg.  ./fvctl.py unregister-event-callback http://127.0.0.1:8000 
# foo FLOWTABLE_CALLBACK alice -d 3
# dpid is optional, if not specified with the -d option, 
# the api will consider it as all dpids.
{
  "url" : <url>,
  "method" : <method_name>,
  "event-type" : <ev_type>,
  "name" : <string>
  "dpid" : <dpid>
}

 <boolean>
Clone this wiki locally