Virtual Network Management API

Basics

Request and Response

Request messages which require body part, they must be properly formatted with the JSON (JavaScript Object Notation). Content-Type must be application/json and other types are not accepted.

Response codes may be "200 OK" or "202 Accepted" if a requested operation is successfully completed or accepted. "202 Accepted" must be interpreted as the request is just accepted and does not mean the operation is successfully completed. The client must proactively check if the operation is successfully completed or not after receiving 202 response.

Response codes may be 4XX or 5XX if a requested operation is not successfully completed. Only typical errors are shown in the tables below and you must prepare for other response codes. Error responses may contain body other format than application/json (e.g. text/plain) for describing errors in detail.

JSON formatting

Any integer values smaller than or equal to 32-bit are represented as integer values. They must not be text strings.

64-bit integer values are represented as text strings for compatibility with different JSON implementations. Several JSON implementations do not accept integer values greater than 32-bit.

API

/networks

Method Request Behavior Response
Parameters Content-Type Body (example) Code Content-Type Body (example)
Key Description
GET - - - - List existing networks. 200 OK application/json list_networks.json
500 Internal error - -
POST id A unique identifier of the network. The value must be a value between 0 and 16777215. If omitted, the value is automatically assigned. application/json create_network.json Create a new network associated. 202 Accepted application/json create_network_response.json
description Description (text string) of the network. If omitted, an empty string is saved. 400 Bad request - -
422 Specified parameters are unacceptable - -
500 Internal error - -

/networks/<net_id>

Method Request Behavior Response
Parameters Content-Type Body (example) Code Content-Type Body (example)
Key Description
GET - - - - Show details of the network identified by net_id. 200 OK application/json show_network.json
404 Not found - -
500 Internal error - -
PUT description Description (text string) of the network. This is a mandatory parameter. application/json modify_network.json Update details of the network identified by net_id. 202 Accepted - -
400 Bad request - -
404 Not found - -
486 Another update is in progress - -
500 Internal error - -
DELETE - - - - Delete the network identified by net_id. 202 Accepted - -
404 Not found - -
486 Another update is in progress - -
500 Internal error - -

/networks/<net_id>/ports

Method Request Behavior Response
Parameters Content-Type Body (example) Code Content-Type Body (example)
Key Description
GET - - - - List all switch ports associated with the network identified by net_id. 200 OK application/json show_ports.json
404 Not found - -
500 Internal error - -
POST id A unique identifier of the switch port. The value must be a value between 1 and 4294967295. If omitted, the value is automatically assigned. application/json create_port.json Attach a switch port to the network identified by net_id. 202 Accepted - -
datapath_id Datapath identifier of the switch which the switch port belongs. The value must be an unsigned 64-bit integer value represented as a text string. This is a mandatory parameter. 400 Bad request - -
number Port number and name of the switch port. Port number must be a value between 1 and 65280. Port name must be a text string. number and name are exclusive and one of them must be provided. 404 Not found - -
name 422 Specified parameters are unacceptable - -
vid VLAN identifier of the switch port. You can multiplex multiple networks on a single switch port with 802.1q VLAN. The value must be a value between 0 and 4095 or equal to 65535. If 65535 is specified, no VLAN is associated. 486 Another update is in progress - -
description Description (text string) of the switch port. If omitted, empty string is saved. 500 Internal error - -

/networks/<net_id>/ports/<port_id>

Method Request Behavior Response
Parameters Content-Type Body (example) Code Content-Type Body (example)
Key Description
GET - - - - Show details of the switch port identified by port_id and net_id. 200 OK application/json show_port.json
404 Not found - -
DELETE - - - - Detach the switch port identified by port_id from the network identified by net_id. 202 Accepted - -
404 Not found - -
486 Another update is in progress - -
500 Internal error - -

/networks/<net_id>/ports/<port_id>/mac_addresses

Method Request Behavior Response
Parameters Content-Type Body (example) Code Content-Type Body (example)
Key Description
GET - - - - List all the mac addresses associated with the switch port. 200 OK application/json show_mac_addresses.json
404 Not found - -
500 Internal error - -
POST address MAC addresses to be associated with the switch port. This is a mandatory parameter. application/json create_mac_address.json Associate a MAC address to the switch port identified by port_id and net_id. 202 Accepted - -
400 Bad request - -
404 Not found - -
422 Specified parameters are unacceptable - -
486 Another update is in progress - -
500 Internal error - -

/networks/<net_id>/ports/<port_id>/mac_addresses/<mac_addresses>

Method Request Behavior Response
Parameters Content-Type Body (example) Code Content-Type Body (example)
Key Description
GET - - - - Check existence of the MAC address. 200 OK application/json show_mac_address.json
404 Not found - -
500 Internal error - -
DELETE - - - - Detach the MAC address from the switch port. 202 Accepted - -
404 Not found - -
486 Another update is in progress - -
500 Internal error - -

Copyright (C) 2012-2013 NEC Corporation