Overview

Background: JSON-RPC Format
Current API Calls (Methods)
OVX API Method Parameters
Notations
API Syntax

Synopsis

OpenVirteX defines two types of API, the Resource API and the Tenant API. The former is read-only and used to get configuration and state information, and the latter is used to create and configure virtual networks.

This page is divided into several sections. We first give a very brief overview of JSON-RPC syntax. We then give a brief overview of each OVX API call, the parameters available to the API, and the conventions used to describe the syntax of the API Calls.

---

Background: JSON-RPC Format

OVX follows the JSON-RPC 2.0 protocol. The syntax for the most commonly-used request and reply messages for the OVX API take the form:

request {"jsonrpc": "2.0", "method": "getSubnet", "params": {"tenant": 1}, "id": 0}
reply   {"jsonrpc": "2.0", "result": "192.168.1.0/16", "id": 0}

A request may also have no params:

{"jsonrpc": "2.0", "method": "getPhysicalTopology", "params":{}, "id":"ovxctl"}

And a reply may have a null result:

{"jsonrpc": "2.0", "result": null, "id": 0}

For the full details of JSON-RPC, refer to their specs.

---

Current API Calls (Methods)

The currently-available API functions are shown in the following two tables. We detail the parameters and results associated with these methods in the next few sections.

---

OVX API Method Parameters

The following table lists the various parameters (values to the JSON “param” key) used by the OVX API. As a convention, we use the Keywords defined by OVX’s API handlers for each parameter as aliases:

---

Notations

We use several notations to describe the API syntax.

A keyword implicitly refers to a parameter: value relation. Example: TENANT is equivalent to

"tenantId": some_int

Elements in braces refers to a map. Example: {DPID, PORT} implies a Map containing two entries:

{ "dpid": some_Long, "port": some_Short }

Elements in square-brackets implies a list of values of the type associated with the keyword. Therefore, [LINK] is:

[ int1, int2, ... intn ] 

Braces in square-brackets would then be a list of Maps. [{LINK, PRIORITY}] implies:

[
    { "linkId": int_1, "priority": byte_1 },
    { "linkId": int_2, "priority": byte_2 },
    ...
]

There are also some non-keyword formatted strings that we refer to:

• String-VDPID – VDPID in colon-hex notation: “00:a4:23:05:xx:xx:xx:xx” (Includes ON.Lab OUI)
• String-DPID – DPID in colon-hex notation: “xx:xx:xx:xx:xx:xx:xx:xx”
• String-VIP – A virtual IP address in dotted decimal: “x.x.x.x”
• String-PIP – A physical IP address in dotted decimal: “x.x.x.x”
• String-LINK – the LinkId, in string or integral form, e.g. “1” or 1

Finally, we also include notations closer to JSON. For example {“switches”: [String-DPID]}, would be a map keyed on the string “switches”, with a list of DPID strings as the value:

{
    "switches": [
        "00:a4:23:05:00:00:00:04", 
        "00:a4:23:05:00:00:00:03", 
        "00:a4:23:05:00:00:00:02",
        "00:a4:23:05:00:00:00:01"
    ]
} 

---

API Syntax

Examples