OpenKilda Northbound API

Last modified by Kevin Austin on 2018/09/13 05:03

The northbound API is documented within OpenKilda using the swagger interface at: http://127.0.0.1:8080/api/v1/swagger-ui.html#/

feature-toggles-controller

Description APIActionParametersResponsesExample ValueType

Get states of feature toggles

/featuresFeatureTogglePayloadGETNo Parameters

200 Operation is successful

401 Unauthorized

403 Forbidden

404 Not Found

{
"create_flow": true,
"delete_flow": true;
"push_flow": true,
"reflow_on_switch_activation": true,
"sync_rules": true,
"unpush_flow": true,
"update_flow": true
}

Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean

Toggle Kilda Features

/featuresFeatureTogglePayloadPOSTrequest
* required

200 Operation is successful

201 Created

401 Unauthorized

403 Forbidden

404 Not Found

{
"create_flow": true,
"delete_flow": true;
"push_flow": true,
"reflow_on_switch_activation": true,
"sync_rules": true,
"unpush_flow": true,
"update_flow": true
}

Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean

flow-controller

Description APIActionParametersResponsesExample ValueType

Dumps all flows

/flowsflow-controllerGETNo Parameters200 Operation is successful

[
  {
     "description": "string",
     "destination": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
  },
       "flowed": "string",
       "ignore_bandwidth": true,
       "last-updated": "string",
       "maximum-bandwidth": 0,
       "periodic-pings": true,
       "source": {
          "port-id": 0,
          "switch-id": {},
          "vlan-id": 0
     },
     "status": "string"
   }
]

string

($int32)
string
($int32)

string
boolean
string
($int64)
boolean

($int32)
string
($int32)

string

401 Unauthorized

403 Forbidden

404 Not Found

500 General Error

503 Service Unavailable

{
     "correlation_id": "string",
     "error-description": "string",
     "error-message": "string",
     "error-type": "string",
     "timestamp": 0
}

string
string
string
string
($int64)

Creates new flow

/flows PUT

flow

*Required

200 Operation is successful

{
     "description": "string",
     "destination": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "flowid": "string",
     "ignore_bandwidth": true,
     "last-updated": "string",
     "maximum-bandwidth": 0,
     "periodic-pings": true,
     "source": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "status": "string"
}

string

($int32)
string ($int32)

string
boolean
string
($int64)
boolean

($int32)
string
($int32)

string

201 Created  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not Found

500 General Error

503 Service Unavailable

{
     "correlation_id" "string",
     "error-description": string",
     "error-message": "string",
     "error-type": "string",
     "timestamp": 0
}

 

Delete all flows

*Requires authorization

/flows DELETE

EXTRA_AUTH

* Required integer ($int64)

200 Operation is successful

{
     "description": "string",
     "destination": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "flowid": "string",
     "ignore_bandwidth": true,
     "last-updated": "string",
     "maximum-bandwidth": 0,
     "periodic-pings": true,
     "source": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "status": "string"
}

 
204 No Content  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not Found

500 General Error

503 Service Unavailable

{
     "correlation_id" "string",
     "error-description": string",
     "error-message": "string",
     "error-type": "string",
     "timestamp": 0
}

 

Ping

Verify flow using a special network packet that is being routed in the same way as client traffic

/flows/{flow_id}/ping PUT

flow_id (string)

* required

payload

* required
 

{
     "timeout": 0
}


($int32)
200 Operation is successful

{
   "error": "string",
   "flow_id": "string",
   "forward": {
     "error": "string",
     "latency": 0,
     "ping_success": true
   },
   "reverse": {
     "error": "string",
     "latency": 0,
     "ping_succcess": true
   }
}

 
201 Created  

400 Invalid Input

401 Unauthorized

403 Forbidden

404 Not Found

500 General Error

503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Reroute flow

/flows/{flow_id}/reroute PATCH

flow_id (string)

* required

200 Operation is successful

{
   "flowid": "string",
   "flowpath": {                                     
     "created_in_cache": 0,
     "latency_ns": 0,
     "timestamp": 0,
         "updated_in_cache":     0,
     "path": [
       {
          "switch_id": {},
          "port_no": 0,
          "seq_id": 0,
          "cookie": 0,
          "segment_latency": 0
       }
     ]
   },
   "rerouted": true
}

 

204 No Content

  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General Error

503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Sync Flow

/flows/{flow_id}/sync PATCH

flow_id (string)

* required

200 Operation is successful

{
   "flowid": "string",
   "flowpath": {                                                                                           
     "created_in_cache": 0,
     "latency_ns": 0,
     "timestamp": 0,                            
     "updated_in_cache":     0,
     "path": [
       {
          "switch_id": {},
          "port_no": 0,
          "seq_id": 0,
          "cookie": 0,
          "segment_latency": 0
       }
     ]
   },
   "rerouted": true
}

 
204 No Content  

400 Invalid Input Data

401 Unauthorized

403 Forbidden

404 Not Found

500 General Error

503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Validate flow

Compare the DB to each switch

/flows/{flow_id}/validate GET

flow_id
(string)
* required

200 Operation is successful

[
   {
     "as_expected": true,
     "byte_counts": [
       0
     ],
     "discrepancies": [
       {
          "actual_value": "string",
          "expected_value": "string",
          "field": "string",
          "rule": "string"
       }
     ],
     "flow_id": "string",
     "flow_rules_total": 0,
     "pkt_counts": [
        0
     ],
     "switch_rules_total": 0
   }
]

 

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not Found

500 General Error

503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Get flow

/flows/{flow-id} GET

flow-id
(string)
* required

200 Operation is successful

{
   "description": "string",
   "destination": {
     "port-id": 0,
     "switch-id": {},
     "vlan-id": 0
   },
   "flowid": "string",
   "ignore_bandwidth": true,
   "last-updated": "string",
   "maximum-bandwidth": 0,
   "periodic-pings": true,
   "source": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "status": "string"
}

 

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General Error

503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Updates Flows

/flows/{flow-id} PUT

flow
* Required

flow-id
(string)
* Required

200 Operation is successful

 

{
   "description": "string",
   "destination": {
     "port-id": 0,
     "switch-id": {},
     "vlan-id": 0
   },
   "flowid": "string",
   "ignore_bandwidth": true,
   "last-updated": "string",
   "maximum-bandwidth": 0,
   "periodic-pings": true,
   "source": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "status": "string"
}

 
201 Created  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General error

503 Service unavailable

 

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Delete Flows

/flows/{flow-id} DELETEflow-id
(string)
* Required
200 Operation is successful

{
   "description": "string",
   "destination": {
     "port-id": 0,
     "switch-id": {},
     "vlan-id": 0
   },
   "flowid": "string",
   "ignore_bandwidth": true,
   "last-updated": "string",
   "maximum-bandwidth": 0,
   "periodic-pings": true,
   "source": {
       "port-id": 0,
       "switch-id": {},
       "vlan-id": 0
     },
     "status": "string"
}

 
204 No Content  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General Error

503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Get flow path

/flows/{flow-id}/path GETflow-id
(string)
* Required
200 Operation is successful

{
   "flowed": "string",
   "flowpath_forward": [
     {
       "input_port": 0,
       "output_port": 0,
       "switch_id": {}
     }
   ],
   "flowpath_reverse": [
     {
       "input_port": 0,
       "output_port": 0,
       "switch_id": {}
       }
     ]
}

 

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General error

503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Invalidate (purge) Flow Cache(s)

/flows/cache DELETENo Parameters200 Operation is successful{
   "added_flows": [
       "string"
     ],
     "dropped_flows": [
       "string"
     ],
     "modified_flows": [
       "string"
     ],
     "unchanged_flows": [
       "string"
     ]
}
 
204 No content  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not Found

500 General error

503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Refresh Flow Cache(s)

/flows/cache PATCHNo Parameters200 Operation is successful{
   "added_flows": [
       "string"
     ],
     "dropped_flows": [
       "string"
     ],
     "modified_flows": [
       "string"
     ],
     "unchanged_flows": [
       "string"
     ]
}
 
204 No content  

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General error

503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Sync Flow Cache(s)

/flows/cachesync GETNo Parameters200 Operation is successful{
   "added_flows": [
       "string"
     ],
     "dropped_flows": [
       "string"
     ],
     "modified_flows": [
       "string"
     ],
     "unchanged_flows": [
       "string"
     ]
}
 

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not found

500 General error

503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Get flow status

/flow/status/{flow-id} GETflow-id
(string)
* Required
200 Operation is successful

{
   "flowid": "string",
   "status": "Allocated"
}

 

400 Invalid input data

401 Unauthorized

403 Forbidden

404 Not Found

500 General error

503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Push flows

Without expectation of modifying switches. It can push to switch and validate.

/push/flows PUT

externalFlows
* Required

propagate
default: false. If true, this will propagate rules to the switches.

verify
default: false. If true, this will wait until poll timeout for validation.

 

[
   {
     "flowid": "string",
     "timestamp": 0,
     "payload": {
       "forward": {
          "flowid": "string",
          "bandwidth": 0,
          "ignore_bandwidth": true,
          "periodic-pings": true,
          "cookie": 0,
          "description": "string",
          "last_updated": "string",
          "src_switch": {},
          "dst_switch": {},
          "src_port": 0,
          "dst_port": 0,
          "src_vlan": 0,
          "dst_vlan": 0,
          "meter_id": 0,
          "transit_vlan": 0,
          "flowpath": {
             "created_in_cache": 0,
             "latency_ns": 0,
             "timestamp": 0,
             "updated_in_cache": 0,
             "path": [
                {
                   "switch_id": {},
                   "port_no": 0,
                   "seq_id": 0,
                   "cookie": 0,
                   "segment_latency": 0
                }
             ]
          },
          "state": "Allocated"
       },

       "reverse": {
          "flowid": "string",
          "bandwidth": 0,
          "ignore_bandwidth": true,
          "periodic-pings": true,
          "cookie": true,
          "description": "string",
          "last_updated": "string",
          "src_switch": {},
          "dst_switch": {},
          "src_port": 0,
          "dst_port": 0,
          "src_vlan": 0,
          "dst_vlan": 0,
          "meter_id": 0,
          "transit_vlan": 0,
          "flowpath": {
             "created_in_cache": 0,
             "latency_ns": 0,
             "timestamp": 0,
             "updated_in_cache": 0,
             "path": [
                {
                   "switch_id": {},
                   "port_no": 0,
                   "seq_id": 0,
                   "cookie": 0,
                   "segment_latency": 0
                }
             ]
          },
          "state": "Allocated"
       }
     },
     "operation": "Create",
     "correlation_id": "string"
   }
]

 

Unpush Flows

unpush flows without expectation of modifying switches. It can push to switch and validate.

/unpush/flows PUT

externalFlows
*required

propagate
default: false. If true, this will propagate rules to the switch.

verify

default: false. If true, will wait until poll timeout for validation.

200 Operation is successful

 

{
   "failures": 0,
   "messages": [
     "string"
   ],
  "successes": 0
}

 
201 Created  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General Error
503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

health-check-controller

Description APIActionParametersResponsesExample ValueType

Health Check

Gets health-check status

/health-check GETNo parameters200 Operation is successful{
   "components": {
     "additionalProp1": "string",
     "additionalProp2": "string",
     "additionalProp3": "string",
   },
   "description": "string",
   "name": "string",
   "version": "string"
}
 
     401 Unauthorized
403 Forbidden
404 Not Found
503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

link-controller

Description APIActionParametersResponsesExample ValueType

Link Properties

Get all link properties (static), based on arguments.

 /link/propsGET

dst_port
integer($int32)

dst_switch
string

src_port
integer($int32)

src_switch
string

200 Operation is successful
 

[
   {
     "dst_port": 0,
     "dst_switch": "string",
     "props": {
       "additionalProp1": "string",
       "additionalProp2": "string",
       "additionalProp3": "string",
     },
     "src_port": 0,
     "src_switch": "string"
   }
]

 
     400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

link props

Create/Update link properties

 /link/propsPUTkeyAndProps
*required
 

[
   {
     "dst_port": 0,
     "dst_switch": "string",
     "props": {
       "additionalProp1": "string",
       "additionalProp2": "string",
       "additionalProp3": "string",
     },
     "src_port": 0,
     "src_switch": "string"
   }
]

 
 200 Operation is successful{
   "failures": 0,
   "messages": [
     "string"
   ],
   "successes": 0
}
 
201 Created  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

delete link properties

Delete link properties (static), based on arguments.

 /link/propsDELETEkeyAndProps
*required
 

[
   {
     "dst_port": 0,
     "dst_switch": "string",
     "props": {
       "additionalProp1": "string",
       "additionalProp2": "string",
       "additionalProp3": "string",
     },
     "src_port": 0,
     "src_switch": "string"
   }
]

 
     200 Operation is successful{
   "failures": 0,
   "messages": [
     "string"
   ],
   "successes": 0
}
 
     400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Get all links

 /linksGETNo Parameters200 Operation is successful

[
   {
     "available_bandwidth": 0,
     "path": [
       {
          "port_no": 0,
          "segment_latency": 0,
          "seq_id": 0,
          "switch_id": "string"
       }
     ],
     "speed": 0,
     "state": "DISCOVERED"
   }
]

 
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General error
503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

switch-controller

Description APIActionParametersResponsesExample ValueType

Get switches

Get all available switches

 /switchesGETNo Parameters200 Operation is successful

{
   "address": "string",
   "description": "string",
   "hostname": string",
   "state": "string",
   "switch_id": "string"
}

 
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Delete meters

Delete meter from the switch

 /switches/{switch_id}/meter/{meter_id}DELETE

meter_id
*required
integer ($int64)

switch_id
*required
string

200 Operation is successful{
   "deleted": true
}
 
204 No Content  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General error
503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

port Config

Configure port on the switch

 

 /switches/{switch_id}/port/{port_no}/configPUT

portConfig
*required

port_no
*required
integer($int32)

switch_id
*required
string

 {
   "status": "UP"
}
 
200 Operation is successful{
   "port_no": 0,
   "switch_id": "string"
}
 
201 Created  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General Error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Synchronize Rules

Synchronize rules on the switch

 /switches/{switch_id}/rules/synchronizeGETswitch_id
*required
string
(path)
200 Operation is successful{
   "excess_rules": [
     0
   ],
   "installed_rules": [
     0
   ],
   "missing_rules": [
     0
   ],
   "proper_rules": [
     0
   ]
}
 
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Validate Rules

Validate the rules installed on the switch

 /switches/{switch_id}/rules/validateGETswitch_id
*required
string
(path)
200 Operation is successful{
   "excess_rules": [
     0
   ],
   "missing_rules": [
     0
   ],
   "proper_rules": [
     0
   ]
}
 
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General error
503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Get rules

Get switch rules from the switch

 /switches/{switch-id}/rulesGETcookie
string
(query)
 Results will be filtered on matching the cookie 
switch-id
*required
string
(path)
 switch-id 
 200 Operation is successful

{
   "flows": [
     {
       "byte-count": 0,
       "cookie": 0,
       "duration-nsec": 0,
       "duration-sec": 0,
       "flags": [
          "string"
       ],
       "hard-timeout": 0,
       "idle-timeout": 0,
       "instructions": {
          "apply_actions": {
             "POP_VLAN": "string",
             "meter": "string",
             "output": "string",
             "push_vlan": "string",
             "set_field": {
                "key": "string",
                "value": "string"
             }
          },
          "instruction_goto_meter": 0,
          "none": "string"
       },
       "match": {
          "eth_dst": "string",
          "eth_type": "string",
          "in_port": "string",
          "ip_proto": "string",
          "udp_dst": "string",
          "udp_src": "string",
          "vlan_id": "string"
       },
       "packet-count": 0,
       "priority": 0,
       "table-id": 0,
       "version": "string"
     }
   ],
   "switch_id": {},
   "timestamp": 0
}

 
 400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Install rules

Install switch rules. Requires special authorization

 /switches/{switch-id}/rulesPUT

install-action
string
(query)

default: INSTALL_DEFAULTS

Can be one of the InstallRuleAction: INSTALL_DROP,
INSTALL_BROADCAST,
INSTALL_UNICAST,
INSTALL_DEFAULTS

switch_id
*required
string
(path)

200 Operation is successful
 
[
   0
]
 
201 Created  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General error
503 Service Unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Delete rules

Delete switch rules. Requires special authorization

 /switches/{switch-id}/rulesDELETE

cookie
string
(query)

delete-action
string
(query)

default: IGNORE_DEFAULTS. Can be one of DeleteRulesAction:

DROP_ALL,
DROP_ALL_ADD_DEFAULTS
IGNORE_DEFAULTS
OVERWRITE_DEFAULTS
REMOVE_DROP
REMOVE_BROADCAST
REMOVE_UNICAST
REMOVE_DEFAULTS
REMOVE_ADD_DEFAULTS

in-port
string
(query)

in-vlan
string
(query)

out-port
string
(query)

priority
string
(query)

switch-id
*required
string
(path)

200 Operation is successful[
   0
]
 
204 No Content  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not Found
500 General error
503 Service Unavailable
 

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

Connect Mode

Set the connect mode if mode is specified. If mode is null, this is effectively a get.

 /switches/toggle-connect-modePUT

mode
*required
Available values:
AUTO
SAFE
MANUAL

200 Operation is successful"AUTO" 
201 Created  
400 Invalid input data
401 Unauthorized
403 Forbidden
404 Not found
500 General error
503 Service unavailable

{
   "correlation_id": "string",
   "error-description": "string",
   "error-message": "string",
   "error-type": "string",
   "timestamp": 0
}

 

 

Tags:
Created by Kevin Austin on 2018/09/05 02:47
©2018 OpenKilda