4. API Reference¶

4.1. Overview¶

spp-ctl provides simple REST like API. It supports http only, not https.

4.1.1. Request and Response¶

Request body is JSON format. It is accepted both text/plain and application/json for the content-type header.

Response of GET is JSON format and the content-type is application/json if the request success.

If a request fails, the response is a text which shows error reason and the content-type is text/plain.

4.1.2. Error code¶

spp-ctl does basic syntax and lexical check of a request.

Table 4.1 Error codes in spp-ctl.¶
Error	Description
400	Syntax or lexical error, or SPP returns error for the request.
404	URL is not supported, or no SPP process of client-id in a URL.
500	System error occured in `spp-ctl`.

4.2. API independent of the process type¶

4.2.1. GET /v1/processes¶

Show the SPP processes connected to the spp-ctl.

Normarl response codes: 200

4.2.1.1. Request example¶

curl -X GET -H 'application/json' \
http://127.0.0.1:7777/v1/processes

4.2.1.2. Response¶

An array of process objects.

process object:

Table 4.2 Response params of getting processes info.¶
Name	Type	Description
type	string	process type. one of `primary`, `nfv` or `vf`.
client-id	integer	client id. if type is `primary` this member does not exist.

4.2.1.3. Response example¶

[
  {
    "type": "primary"
  },
  {
    "type": "vf",
    "client-id": 1
  },
  {
    "type": "nfv",
    "client-id": 2
  }
]

4.3. API for spp_primary¶

4.3.1. GET /v1/primary/status¶

Show statistical information.

Normal response codes: 200

4.3.1.1. Request example¶

curl -X GET -H 'application/json' \
http://127.0.0.1:7777/v1/primary/status

4.3.1.2. Response¶

Table 4.3 Response params of primary status.¶
Name	Type	Description
phy_ports	array	An array of statistics of physical ports.
ring_ports	array	An array of statistics of ring ports.

Physical port object.

Table 4.4 Attributes of physical port of primary status.¶
Name	Type	Description
id	integer	Port ID of the physical port.
rx	integer	The total number of received packets.
tx	integer	The total number of transferred packets.
tx_drop	integer	The total number of dropped packets of transferred.
eth	string	MAC address of the port.

Ring port object.

Table 4.5 Attributes of ring port of primary status.¶
Name	Type	Description
id	integer	Port ID of the ring port.
rx	integer	The total number of received packets.
rx_drop	integer	The total number of dropped packets of received.
tx	integer	The total number of transferred packets.
tx_drop	integer	The total number of dropped packets of transferred.

4.3.1.3. Response example¶

{
  "phy_ports": [
    {
      "id": 0,
      "rx": 0,
      "tx": 0,
      "tx_drop": 0,
      "eth": "56:48:4f:53:54:00"
    },
    {
      "id": 1,
      "rx": 0,
      "tx": 0,
      "tx_drop": 0,
      "eth": "56:48:4f:53:54:01"
    }
  ],
  "ring_ports": [
    {
      "id": 0,
      "rx": 0,
      "rx_drop": 0,
      "tx": 0,
      "tx_drop": 0
    },
    {
      "id": 1,
      "rx": 0,
      "rx_drop": 0,
      "tx": 0,
      "tx_drop": 0
    },
    {
      "id": 2,
      "rx": 0,
      "rx_drop": 0,
      "tx": 0,
      "tx_drop": 0
    },
    {
      "id": 3,
      "rx": 0,
      "rx_drop": 0,
      "tx": 0,
      "tx_drop": 0
    }
  ]
}

4.3.2. DELETE /v1/primary/status¶

Clear statistical information.

Normal response codes: 204

4.3.2.1. Request example¶

curl -X DELETE -H 'application/json' \
http://127.0.0.1:7777/v1/primary/status

4.3.2.2. Response¶

There is no body content for the response of a successful DELETE request.

4.3.3. DELETE /v1/primary¶

Terminate primary process.

Normal response codes: 204

4.3.3.1. Request example¶

curl -X DELETE -H 'application/json' \
http://127.0.0.1:7777/v1/primary

4.3.3.2. Response¶

There is no body content for the response of a successful DELETE request.

4.4. API for spp_nfv/spp_vm¶

4.4.1. GET /v1/nfvs/{client_id}¶

Get the information of the spp_nfv or spp_vm process.

Normal response codes: 200
Error response codes: 400, 404

4.4.1.1. Request(path)¶

Table 4.6 Request parameter for getting spp_nfv or spp_vm info.¶
Name	Type	Description
client_id	integer	client id.

4.4.1.2. Request example¶

curl -X GET -H 'application/json' \
http://127.0.0.1:7777/v1/nfvs/1

4.4.1.3. Response¶

Table 4.7 Response params of getting spp_nfv or spp_vm info.¶
Name	Type	Description
client-id	integer	client id.
status	string	`Running` or `Idle`.
ports	array	an array of port ids used by the process.
patches	array	an array of patches.

patch objest

Table 4.8 Attributes of patch of spp_nfv or spp_vm.¶
Name	Type	Description
src	string	source port id.
dst	string	destination port id.

4.4.1.4. Response example¶

{
  "client-id": 1,
  "status": "Running",
  "ports": [
    "phy:0", "phy:1", "vhost:0", "vhost:1", "ring:0", "ring:1", "ring:2", "ring:3"
  ],
  "patches": [
    {
      "src": "vhost:0", "dst": "ring:0"
    },
    {
      "src": "ring:1", "dst": "vhost:1"
    }
  ]
}

4.4.1.5. Equivalent CLI command¶

sec {client_id};status

4.4.2. PUT /v1/nfvs/{client_id}/forward¶

Start or Stop forwarding.

Normal response codes: 204
Error response codes: 400, 404

4.4.2.1. Request(path)¶

Table 4.9 Request params of forward of spp_nfv or spp_vm.¶
Name	Type	Description
client_id	integer	client id.

4.4.2.2. Request example¶

curl -X PUT -H 'application/json' \
-d '{"action": "start"}' \
http://127.0.0.1:7777/v1/nfvs/1/forward

4.4.2.3. Request(body)¶

Table 4.10 Request body params of forward of spp_nfv or spp_vm.¶
Name	Type	Description
action	string	`start` or `stop`.

4.4.2.4. Response¶

There is no body content for the response of a successful PUT request.

4.4.2.5. Equivalent CLI command¶

action is start

sec {client_id};forward

action is stop

sec {client_id};stop

4.4.3. PUT /v1/nfvs/{client_id}/ports¶

Add or Delete port.

Normal response codes: 204
Error response codes: 400, 404

4.4.3.1. Request(path)¶

Table 4.11 Request params of ports of spp_nfv or spp_vm.¶
Name	Type	Description
client_id	integer	client id.

4.4.3.2. Request(body)¶

Table 4.12 Request body params of ports of spp_nfv or spp_vm.¶
Name	Type	Description
action	string	`add` or `del`.
port	string	port id. port id is the form {interface_type}:{interface_id}.

4.4.3.3. Request example¶

curl -X PUT -H 'application/json' \
-d '{"action": "add", "port": "ring:0"}' \
http://127.0.0.1:7777/v1/nfvs/1/ports

4.4.3.4. Response¶

There is no body content for the response of a successful PUT request.

4.4.3.5. Equivalent CLI command¶

sec {client_id};{action} {interface_type} {interface_id}

4.4.4. PUT /v1/nfvs/{client_id}/patches¶

Add a patch.

Normal response codes: 204
Error response codes: 400, 404

4.4.4.1. Request(path)¶

Table 4.13 Request params of patches of spp_nfv or spp_vm.¶
Name	Type	Description
client_id	integer	client id.

4.4.4.2. Request(body)¶

Table 4.14 Request body params of patches of spp_nfv or spp_vm.¶
Name	Type	Description
src	string	source port id.
dst	string	destination port id.

4.4.4.3. Request example¶

curl -X PUT -H 'application/json' \
-d '{"src": "ring:0", "dst": "ring:1"}' \
http://127.0.0.1:7777/v1/nfvs/1/patches

4.4.4.4. Response¶

There is no body content for the response of a successful PUT request.

4.4.4.5. Equivalent CLI command¶

sec {client_id};patch {src} {dst}

4.4.5. DELETE /v1/nfvs/{client_id}/patches¶

Reset patches.

Normal response codes: 204
Error response codes: 400, 404

4.4.5.1. Request(path)¶

Table 4.15 Request params of deleting patches of spp_nfv or spp_vm.¶
Name	Type	Description
client_id	integer	client id.

4.4.5.2. Request example¶

curl -X DELETE -H 'application/json' \
http://127.0.0.1:7777/v1/nfvs/1/patches

4.4.5.3. Response¶

There is no body content for the response of a successful DELETE request.

4.4.5.4. Equivalent CLI command¶

sec {client_id};patch reset

4.4.6. DELETE /v1/nfvs/{client_id}¶

Terminate spp_nfv or spp_vm process.

Normal response codes: 204
Error response codes: 400, 404

4.4.6.1. Request(path)¶

Table 4.16 Request parameter for terminating spp_nfv or spp_vm.¶
Name	Type	Description
client_id	integer	client id.

4.4.6.2. Request example¶

curl -X DELETE -H 'application/json' \
http://127.0.0.1:7777/v1/nfvs/1

4.4.6.3. Response example¶

There is no body content for the response of a successful DELETE request.

4.4.6.4. Equivalent CLI command¶

sec {client_id}; exit

4.5. API for spp_vf¶

4.5.1. GET /v1/vfs/{client_id}¶

Get the information of the spp_vf process.

Normal response codes: 200
Error response codes: 400, 404

4.5.1.1. Request(path)¶

Table 4.17 Request parameter for getting spp_vf.¶
Name	Type	Description
client_id	integer	client id.

4.5.1.2. Request example¶

curl -X GET -H 'application/json' \
http://127.0.0.1:7777/v1/vfs/1

4.5.1.3. Response¶

Table 4.18 Response params of getting spp_vf.¶
Name	Type	Description
client-id	integer	client id.
ports	array	an array of port ids used by the process.
components	array	an array of component objects in the process.
classifier_table	array	an array of classifier tables in the process.

component object:

Table 4.19 Component objects of getting spp_vf.¶
Name	Type	Description
core	integer	core id running on the component
name	string	an array of port ids used by the process.
type	string	an array of component objects in the process.
rx_port	array	an array of port objects connected to the rx side of the component.
tx_port	array	an array of port objects connected to the tx side of the component.

port object:

Table 4.20 Port objects of getting spp_vf.¶
Name	Type	Description
port	string	port id. port id is the form {interface_type}:{interface_id}.
vlan	object	vlan operation which is applied to the port.

vlan object:

Table 4.21 Vlan objects of getting spp_vf.¶
Name	Type	Description
operation	string	`add`, `del` or `none`.
id	integer	vlan id.
pcp	integer	vlan pcp.

classifier table:

Table 4.22 Vlan objects of getting spp_vf.¶
Name	Type	Description
type	string	`mac` or `vlan`.
value	string	mac_address for `mac`, vlan_id/mac_address for `vlan`.
port	string	port id applied to classify.

4.5.1.4. Response example¶

{
  "client-id": 1,
  "ports": [
    "phy:0", "phy:1", "vhost:0", "vhost:1", "ring:0", "ring:1", "ring:2", "ring:3"
  ],
  "components": [
    {
      "core": 2,
      "name": "forward_0_tx",
      "type": "forward",
      "rx_port": [
        {
        "port": "ring:0",
        "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ],
      "tx_port": [
        {
          "port": "vhost:0",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ]
    },
    {
      "core": 3,
      "type": "unuse"
    },
    {
      "core": 4,
      "type": "unuse"
    },
    {
      "core": 5,
      "name": "forward_1_rx",
      "type": "forward",
      "rx_port": [
        {
        "port": "vhost:1",
        "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ],
      "tx_port": [
        {
          "port": "ring:3",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ]
    },
    {
      "core": 6,
      "name": "classifier",
      "type": "classifier_mac",
      "rx_port": [
        {
          "port": "phy:0",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ],
      "tx_port": [
        {
          "port": "ring:0",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        },
        {
          "port": "ring:2",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ]
    },
    {
      "core": 7,
      "name": "merger",
      "type": "merge",
      "rx_port": [
        {
          "port": "ring:1",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        },
        {
          "port": "ring:3",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ],
      "tx_port": [
        {
          "port": "phy:0",
          "vlan": { "operation": "none", "id": 0, "pcp": 0 }
        }
      ]
    },
  ],
  "classifier_table": [
    {
      "type": "mac",
      "value": "FA:16:3E:7D:CC:35",
      "port": "ring:0"
    }
  ]
}

The component which type is unused is to indicate unused core.

4.5.1.5. Equivalent CLI command¶

sec {client_id};status

4.5.2. POST /v1/vfs/{client_id}/components¶

Start the component.

Normal response codes: 204
Error response codes: 400, 404

4.5.2.1. Request(path)¶

Table 4.23 Request params of components of spp_vf.¶
Name	Type	Description
client_id	integer	client id.

4.5.2.2. Request(body)¶

Table 4.24 Response params of components of spp_vf.¶
Name	Type	Description
name	string	component name. must be unique in the process.
core	integer	core id.
type	string	component type. one of `forward`, `merge` or `classifier_mac`.

4.5.2.3. Request example¶

curl -X POST -H 'application/json' \
-d '{"name": "forwarder1", "core": 12, "type": "forward"}' \
http://127.0.0.1:7777/v1/vfs/1/components

4.5.2.4. Response¶

There is no body content for the response of a successful POST request.

4.5.2.5. Equivalent CLI command¶

sec {client_id};component start {name} {core} {type}

4.5.3. DELETE /v1/vfs/{sec id}/components/{name}¶

Stop the component.

Normal response codes: 204
Error response codes: 400, 404

4.5.3.1. Request(path)¶

Table 4.25 Request params of deleting component of spp_vf.¶
Name	Type	Description
client_id	integer	client id.
name	string	component name.

4.5.3.2. Request example¶

curl -X DELETE -H 'application/json' \
http://127.0.0.1:7777/v1/vfs/1/components/forwarder1

4.5.3.3. Response¶

There is no body content for the response of a successful POST request.

4.5.3.4. Equivalent CLI command¶

sec {client_id};component stop {name}

4.5.4. PUT /v1/vfs/{client_id}/components/{name}/ports¶

Add or Delete port to the component.

Normal response codes: 204
Error response codes: 400, 404

4.5.4.1. Request(path)¶

Table 4.26 Request params for ports of component of spp_vf.¶
Name	Type	Description
client_id	integer	client id.
name	string	component name.

4.5.4.2. Request(body)¶

Table 4.27 Request body params for ports of component of spp_vf.¶
Name	Type	Description
action	string	`attach` or `detach`.
port	string	port id. port id is the form {interface_type}:{interface_id}.
dir	string	`rx` or `tx`.
vlan	object	vlan operation which is applied to the port. it can be omitted.

vlan object:

Table 4.28 Request body params for vlan ports of component of spp_vf.¶
Name	Type	Description
operation	string	`add`, `del` or `none`.
id	integer	vlan id. ignored when operation is `del` or `none`.
pcp	integer	vlan pcp. ignored when operation is `del` or `none`.

4.5.4.3. Request example¶

curl -X PUT -H 'application/json' \
-d '{"action": "attach", "port": "vhost:1", "dir": "rx", \
     "vlan": {"operation": "add", "id": 677, "pcp": 0}}' \
http://127.0.0.1:7777/v1/vfs/1/components/forwarder1/ports

curl -X PUT -H 'application/json' \
-d '{"action": "detach", "port": "vhost:0", "dir": "tx"} \
http://127.0.0.1:7777/v1/vfs/1/components/forwarder1/ports

4.5.4.4. Response¶

There is no body content for the response of a successful PUT request.

4.5.4.5. Equivalent CLI command¶

action is attach

sec {client_id};port add {port} {dir} {name} [add_vlantag {id} {pcp} | del_vlantag]

action is detach

sec {client_id};port del {port} {dir} {name}

4.5.5. PUT /v1/vfs/{sec id}/classifier_table¶

Set or Unset classifier table.

Normal response codes: 204
Error response codes: 400, 404

4.5.5.1. Request(path)¶

Table 4.29 Request params for classifier_table of spp_vf.¶
Name	Type	Description
client_id	integer	client id.

4.5.5.2. Request(body)¶

Table 4.30 Request body params for classifier_table of spp_vf.¶
Name	Type	Description
action	string	`add` or `del`.
type	string	`mac` or `vlan`.
vlan	integer or null	vlan id for `vlan`. null or omitted for `mac`.
mac_address	string	mac address.
port	string	port id.

4.5.5.3. Request example¶

curl -X PUT -H 'application/json' \
-d '{"action": "add", "type": "mac", "mac_address": "FA:16:3E:7D:CC:35", \
   "port": "ring:0"}' \
http://127.0.0.1:7777/v1/vfs/1/classifier_table

curl -X PUT -H 'application/json' \
-d '{"action": "del", "type": "vlan", "vlan": 475, \
   "mac_address": "FA:16:3E:7D:CC:35", "port": "ring:0"}' \
http://127.0.0.1:7777/v1/vfs/1/classifier_table

4.5.5.4. Response¶

There is no body content for the response of a successful PUT request.

4.5.5.5. Equivalent CLI command¶

type is mac

classifier_table {action} mac {mac_address} {port}

type is vlan

classifier_table {action} vlan {vlan} {mac_address} {port}

4.6. API for spp_mirror¶

4.6.1. GET /v1/mirrors/{client_id}¶

Get the information of the spp_mirror process.

Normal response codes: 200
Error response codes: 400, 404

4.6.1.1. Request(path)¶

Table 4.31 Request parameter for getting spp_mirror.¶
Name	Type	Description
client_id	integer	client id.

4.6.1.2. Request example¶

curl -X GET -H 'application/json' \
http://127.0.0.1:7777/v1/mirrors/1

4.6.1.3. Response¶

Table 4.32 Response params of getting spp_mirror.¶
Name	Type	Description
client-id	integer	client id.
ports	array	an array of port ids used by the process.
components	array	an array of component objects in the process.

component object:

Table 4.33 Component objects of getting spp_mirror.¶
Name	Type	Description
core	integer	core id running on the component
name	string	an array of port ids used by the process.
type	string	an array of component objects in the process.
rx_port	array	an array of port objects connected to the rx side of the component.
tx_port	array	an array of port objects connected to the tx side of the component.

port object:

Table 4.34 Port objects of getting spp_vf.¶
Name	Type	Description
port	string	port id. port id is the form {interface_type}:{interface_id}.

4.6.1.4. Response example¶

{
  "client-id": 1,
  "ports": [
    "phy:0", "phy:1", "ring:0", "ring:1", "ring:2"
  ],
  "components": [
    {
      "core": 2,
      "name": "mirror_0",
      "type": "mirror",
      "rx_port": [
        {
        "port": "ring:0"
        }
      ],
      "tx_port": [
        {
          "port": "ring:1"
        },
        {
          "port": "ring:2"
        }
      ]
    },
    {
      "core": 3,
      "type": "unuse"
    }
  ]
}

The component which type is unused is to indicate unused core.

4.6.1.5. Equivalent CLI command¶

sec {client_id};status

4.6.2. POST /v1/mirrors/{client_id}/components¶

Start the component.

Normal response codes: 204
Error response codes: 400, 404

4.6.2.1. Request(path)¶

Table 4.35 Request params of components of spp_mirror.¶
Name	Type	Description
client_id	integer	client id.

4.6.2.2. Request(body)¶

Table 4.36 Response params of components of spp_mirror.¶
Name	Type	Description
name	string	component name. must be unique in the process.
core	integer	core id.
type	string	component type. only `mirror` is available.

4.6.2.3. Request example¶

curl -X POST -H 'application/json' \
-d '{"name": "mirror_1", "core": 12, "type": "mirror"}' \
http://127.0.0.1:7777/v1/mirrors/1/components

4.6.2.4. Response¶

There is no body content for the response of a successful POST request.

4.6.2.5. Equivalent CLI command¶

sec {client_id};component start {name} {core} {type}

4.6.3. DELETE /v1/mirrors/{client_id}/components/{name}¶

Stop the component.

Normal response codes: 204
Error response codes: 400, 404

4.6.3.1. Request(path)¶

Table 4.37 Request params of deleting component of spp_mirror.¶
Name	Type	Description
client_id	integer	client id.
name	string	component name.

4.6.3.2. Request example¶

curl -X DELETE -H 'application/json' \
http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1

4.6.3.3. Response¶

There is no body content for the response of a successful POST request.

4.6.3.4. Equivalent CLI command¶

sec {client_id};component stop {name}

4.6.4. PUT /v1/mirrors/{client_id}/components/{name}/ports¶

Add or Delete port to the component.

Normal response codes: 204
Error response codes: 400, 404

4.6.4.1. Request(path)¶

Table 4.38 Request params for ports of component of spp_mirror.¶
Name	Type	Description
client_id	integer	client id.
name	string	component name.

4.6.4.2. Request(body)¶

Table 4.39 Request body params for ports of component of spp_mirror.¶
Name	Type	Description
action	string	`attach` or `detach`.
port	string	port id. port id is the form {interface_type}:{interface_id}.
dir	string	`rx` or `tx`.

4.6.4.3. Request example¶

curl -X PUT -H 'application/json' \
-d '{"action": "attach", "port": "ring:1", "dir": "rx"}' \
http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports

curl -X PUT -H 'application/json' \
-d '{"action": "detach", "port": "ring:0", "dir": "tx"} \
http://127.0.0.1:7777/v1/mirrors/1/components/mirror_1/ports

4.6.4.4. Response¶

There is no body content for the response of a successful PUT request.

4.6.4.5. Equivalent CLI command¶

action is attach

sec {client_id};port add {port} {dir} {name}

action is detach

sec {client_id};port del {port} {dir} {name}