From: Itsuro ODA <oda@valinux.co.jp>
To: spp@dpdk.org
Subject: [spp] [PATCH v2 2/9] docs: api reference
Date: Sun, 23 Sep 2018 11:28:22 +0900 [thread overview]
Message-ID: <20180923112822.2D79.277DD91C@valinux.co.jp> (raw)
In-Reply-To: <20180923112233.2D71.277DD91C@valinux.co.jp>
From: Itsuro Oda <oda@valinux.co.jp>
Signed-off-by: Itsuro Oda <oda@valinux.co.jp>
---
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 <oda@valinux.co.jp>
next prev parent reply other threads:[~2018-09-23 2:28 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-09-23 2:22 [spp] [PATCH v2 0/9] spp-ctl: SPP controller with Web API Itsuro ODA
2018-09-23 2:25 ` [spp] [PATCH v2 1/9] docs: overview Itsuro ODA
2018-10-02 3:29 ` Yasufumi Ogawa
2018-09-23 2:28 ` Itsuro ODA [this message]
2018-10-02 3:42 ` [spp] [PATCH v2 2/9] docs: api reference Yasufumi Ogawa
2018-10-02 4:10 ` Yasufumi Ogawa
2018-09-23 2:30 ` [spp] [PATCH v2 3/9] docs: index Itsuro ODA
2018-09-23 2:32 ` [spp] [PATCH v2 4/9] docs: top index Itsuro ODA
2018-09-23 2:33 ` [spp] PATCH v2 5/9] add requirements.txt Itsuro ODA
2018-09-23 2:35 ` [spp] [PATCH v2 6/9] spp-ctl: executable Itsuro ODA
2018-10-02 5:47 ` Yasufumi Ogawa
2018-09-23 2:36 ` [spp] [PATCH v2 7/9] spp-ctl: SPP controller with Web API Itsuro ODA
2018-09-23 2:44 ` Itsuro ODA
2018-09-25 2:01 ` Yasufumi Ogawa
2018-09-23 2:38 ` [spp] [PATCH v2 8/9] spp-ctl: web api handler Itsuro ODA
2018-10-02 4:03 ` Yasufumi Ogawa
2018-09-23 2:39 ` [spp] [PATCH v2 9/9] spp-ctl: spp command interface Itsuro ODA
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180923112822.2D79.277DD91C@valinux.co.jp \
--to=oda@valinux.co.jp \
--cc=spp@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).