From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail.valinux.co.jp (mail.valinux.co.jp [210.128.90.3]) by dpdk.org (Postfix) with ESMTP id A1B14255 for ; Sun, 23 Sep 2018 04:28:23 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by mail.valinux.co.jp (Postfix) with ESMTP id BE108B3C73 for ; Sun, 23 Sep 2018 11:28:22 +0900 (JST) X-Virus-Scanned: Debian amavisd-new at valinux.co.jp Received: from mail.valinux.co.jp ([127.0.0.1]) by localhost (mail.valinux.co.jp [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id WNI4CnSpvJOe for ; Sun, 23 Sep 2018 11:28:22 +0900 (JST) Received: from [127.0.0.1] (vagw.valinux.co.jp [210.128.90.14]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.valinux.co.jp (Postfix) with ESMTPS id 93D3FB3C68 for ; Sun, 23 Sep 2018 11:28:22 +0900 (JST) Date: Sun, 23 Sep 2018 11:28:22 +0900 From: Itsuro ODA To: spp@dpdk.org In-Reply-To: <20180923112233.2D71.277DD91C@valinux.co.jp> References: <20180923112233.2D71.277DD91C@valinux.co.jp> Message-Id: <20180923112822.2D79.277DD91C@valinux.co.jp> MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Mailer: Becky! ver. 2.71.01 [ja] Subject: [spp] [PATCH v2 2/9] docs: api reference X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 23 Sep 2018 02:28:24 -0000 From: Itsuro Oda Signed-off-by: Itsuro Oda --- docs/guides/spp-ctl/api-reference.rst | 790 ++++++++++++++++++++++++++ 1 file changed, 790 insertions(+) create mode 100644 docs/guides/spp-ctl/api-reference.rst diff --git a/docs/guides/spp-ctl/api-reference.rst b/docs/guides/spp-ctl/api-reference.rst new file mode 100644 index 0000000..b8bf488 --- /dev/null +++ b/docs/guides/spp-ctl/api-reference.rst @@ -0,0 +1,790 @@ +============= +API Reference +============= + +Overview +======== + +Spp-ctl provides simple REST like API. It supports http only, not https. + +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". + +Error code +---------- + +Spp-ctl does basic syntax and lexical check of a request. + ++-------+------------------------------------------------------------------------------+ +| Error | Description | ++=======+==============================================================================+ +| 400 | Syntax or lexical error of a request. | +| | Or an SPP process returns error for the command correspondings to a request. | ++-------+------------------------------------------------------------------------------+ +| 404 | URL is not supported for spp-ctl. | +| | Or there is no SPP process of client-id in a URL. | ++-------+------------------------------------------------------------------------------+ +| 500 | A system error occurs in the spp-ctl. | +| | ex. communication error between an SPP processes. | ++-------+------------------------------------------------------------------------------+ + + +API independent of the process type +=================================== + +GET /v1/processes +----------------- + +Show the SPP processes connected to the spp-ctl. + +Normarl response codes: 200 + +Response +^^^^^^^^ + +An array of process objects. + +process object: + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| type | string | process type. one of "primary", "vf" or "nfv". | ++-----------+---------+-------------------------------------------------------------+ +| client-id | integer | client id. if type is "primary" this member does not exist. | ++-----------+---------+-------------------------------------------------------------+ + +Response example +^^^^^^^^^^^^^^^^ + +:: + +[{"type": "primary"}, {"type": "vf", "client-id": 1}, {"type": "nfv", "client-id": 2}] + + +API for spp_vf +============== + +GET /v1/vfs/{client_id} +----------------------- + +Get the information of the spp_vf process. + +Normal response codes: 200 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Response +^^^^^^^^ + ++------------------+---------+-------------------------------------------------------------+ +| 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: + ++---------+---------+---------------------------------------------------------------------+ +| 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: + ++---------+---------+---------------------------------------------------------------------+ +| 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: + ++-----------+---------+-------------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+===================================================================+ +| operation | string | "add", "del" or "none". | ++-----------+---------+-------------------------------------------------------------------+ +| id | integer | vlan id. | ++-----------+---------+-------------------------------------------------------------------+ +| pcp | integer | vlan pcp. | ++-----------+---------+-------------------------------------------------------------------+ + +classifier table: + ++-----------+---------+----------------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+======================================================================+ +| type | string | "mac" or "vlan". | ++-----------+---------+----------------------------------------------------------------------+ +| value | string | "mac address" for "mac" type. "vlan id/mac address" for "vlan" type. | ++-----------+---------+----------------------------------------------------------------------+ +| port | string | port id applied to classify. | ++-----------+---------+----------------------------------------------------------------------+ + +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" +} +] +} + +Note: The component which type is "unused" is to indicate unused core. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};status + + +POST /v1/vfs/{client_id}/components +----------------------------------- + +Start the component. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + + +Request(body) +^^^^^^^^^^^^^ + ++-----------+---------+----------------------------------------------------------------+ +| 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". | ++-----------+---------+----------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ +:: + +{"name": "forwarder1", "core": 12, "type": "forward"} + +Response +^^^^^^^^ + +There is no body content for the response of a successful POST request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};component start {name} {core} {type} + + +DELETE /v1/vfs/{sec id}/components/{name} +----------------------------------------- + +Stop the component. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ +| name | string | component name. | ++-----------+---------+-------------------------------------------------------------+ + +Response +^^^^^^^^ + +There is no body content for the response of a successful POST request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};component stop {name} + + +PUT /v1/vfs/{client_id}/components/{name}/ports +----------------------------------------------- + +Add or Delete port to the component. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ +| name | string | component name. | ++-----------+---------+-------------------------------------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + ++---------+---------+---------------------------------------------------------------------+ +| 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: + ++-----------+---------+-------------------------------------------------------------------+ +| 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". | ++-----------+---------+-------------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +:: + +{"action": "attach", "port": "vhost:1", "dir": "rx", +"vlan": {"operation": "add", "id": 677, "pcp": 0} +} + +:: + +{"action": "detach", "port": "vhost:0", "dir": "tx"} + + +Response +^^^^^^^^ + +There is no body content for the response of a successful PUT request. + + +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} + + +PUT /v1/vfs/{sec id}/classifier_table +------------------------------------- + +Set or Unset classifier table. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + ++-------------+-----------------+-------------------------------------------------------------------+ +| Name | Type | Description | ++=============+=================+===================================================================+ +| action | string | "add" or "del". | ++-------------+-----------------+-------------------------------------------------------------------+ +| type | string | "mac" or "vlan". | ++-------------+-----------------+-------------------------------------------------------------------+ +| vlan | integer or null | vlan id when type is "vlan. null or omitted when type is "mac". | ++-------------+-----------------+-------------------------------------------------------------------+ +| mac_address | string | mac address. | ++-------------+-----------------+-------------------------------------------------------------------+ +| port | string | port id. | ++-------------+-----------------+-------------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +:: + +{"action": "add", "type": "mac", +"mac_address": "FA:16:3E:7D:CC:35", "port": "ring:0" +} + +:: + +{"action": "del", "type": "vlan", "vlan": 475, +"mac_address": "FA:16:3E:7D:CC:35", "port": "ring:0" +} + + +Response +^^^^^^^^ + +There is no body content for the response of a successful PUT request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +type is "mac" + +:: + +classifier_table {action} mac {mac_address} {port} + +type is "vlan" + +:: + +classifier_table {action} vlan {vlan} {mac_address} {port} + + +API for spp_nfv/spp_vm +====================== + +GET /v1/nfvs/{client_id} +------------------------ + +Get the information of the spp_nfv/spp_vm process. + +Normal response codes: 200 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Response +^^^^^^^^ + ++------------------+---------+-------------------------------------------------------------+ +| 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 + ++----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+=============================================================+ +| src | string | source port id. | ++----------+---------+-------------------------------------------------------------+ +| dst | string | destination port id. | ++----------+---------+-------------------------------------------------------------+ + +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"} +] +} + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};status + + +PUT /v1/nfvs/{client_id}/forward +-------------------------------- + +Start or Stop forwarding. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| action | string | "start" or "stop". | ++-----------+---------+-------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +:: + +{"action": "start"} + +Response +^^^^^^^^ + +There is no body content for the response of a successful PUT request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +action is "start" + +:: + +sec {client_id};forward + +action is "stop" + +:: + +sec {client_id};stop + + +PUT /v1/nfvs/{client_id}/ports +------------------------------ + +Add or Delete port. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + ++-----------+---------+---------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+===============================================================+ +| action | string | "add" or "del". | ++-----------+---------+---------------------------------------------------------------+ +| port | string | port id. port id is the form {interface_type}:{interface_id}. | ++-----------+---------+---------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +:: + +{"action": "add", "port": "vhost:0"} + + +Response +^^^^^^^^ + +There is no body content for the response of a successful PUT request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};{action} {interface_type} {interface_id} + + +PUT /v1/nfvs/{client_id}/patches +-------------------------------- + +Add a patch. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Request(body) +^^^^^^^^^^^^^ + ++----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+=============================================================+ +| src | string | source port id. | ++----------+---------+-------------------------------------------------------------+ +| dst | string | destination port id. | ++----------+---------+-------------------------------------------------------------+ + +Request example +^^^^^^^^^^^^^^^ + +:: + +{"src": "vhost:0", "dst": "ring:0"} + +Response +^^^^^^^^ + +There is no body content for the response of a successful PUT request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};patch {src} {dst} + + +DELETE /v1/nfvs/{client_id}/patches +----------------------------------- + +Reset patches. + +Normal response codes: 204 + +Error response codes: 400, 404 + +Request(path) +^^^^^^^^^^^^^ + ++-----------+---------+-------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+=============================================================+ +| client_id | integer | client id. | ++-----------+---------+-------------------------------------------------------------+ + +Response +^^^^^^^^ + +There is no body content for the response of a successful DELETE request. + +Equivalent CLI command +^^^^^^^^^^^^^^^^^^^^^^ + +:: + +sec {client_id};patch reset + + +API for spp_primary +=================== + +GET /v1/primary/status +---------------------- + +Show statistical information. + +Normal response codes: 200 + +Response +^^^^^^^^ + +There is no data at the moment. The statistical information will be returned when spp_primary +implements it. + + +DELETE /v1/primary/status +------------------------- + +Clear statistical information. + +Normal response codes: 204 + +Response +^^^^^^^^ + +There is no body content for the response of a successful PUT request. + -- 2.17.0 -- Itsuro ODA