summaryrefslogtreecommitdiffstats
path: root/docs/testing/user/userguide/06-How_to_use_REST_api.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/testing/user/userguide/06-How_to_use_REST_api.rst')
-rw-r--r--docs/testing/user/userguide/06-How_to_use_REST_api.rst169
1 files changed, 88 insertions, 81 deletions
diff --git a/docs/testing/user/userguide/06-How_to_use_REST_api.rst b/docs/testing/user/userguide/06-How_to_use_REST_api.rst
index 658f99d3..64c68a4f 100644
--- a/docs/testing/user/userguide/06-How_to_use_REST_api.rst
+++ b/docs/testing/user/userguide/06-How_to_use_REST_api.rst
@@ -8,7 +8,7 @@ REST API
========================================================
Introduction
-===============
+---------------
As the internet industry progresses creating REST API becomes more concrete
with emerging best Practices. RESTful web services don’t follow a prescribed
standard except fpr the protocol that is used which is HTTP, its important
@@ -30,7 +30,7 @@ Here are important points to be considered:
REST API in SampleVNF
-=====================
+---------------------
In SampleVNF project VNF’s are run under different contexts like BareMetal,
SRIOV, OVS & Openstack etc. It becomes difficult to interact with the
@@ -45,7 +45,7 @@ REST api on VNF’s will help adapting with the new automation techniques
being adapted in yardstick.
Web server integration with VNF’s
-==================================
+----------------------------------
In order to implement REST api’s in VNF one of the first task is to
identify a simple web server that needs to be integrated with VNF’s.
@@ -66,93 +66,102 @@ for different URI’s that are implemented.
Typical usage is shown below
URI definition for different VNF’s
-----------------------------------
-::
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- | **URI** | **REST Method** | **Arguments** |**Description** |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf | GET | None |Displays top level methods available |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config | GET | None |Displays the current config set |
- | | POST | pci_white_list: | |
- | | | num_worker(o): | |
- | | | vnf_type(o): | |
- | | | pkt_type (o): | |
- | | | num_lb(o): | |
- | | | sw_lb(o): | |
- | | | sock_in(o): | |
- | | | hyperthread(o): | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/arp | GET | None |Displays ARP/ND info |
- | | POST | action: <add/del/req> | |
- | | | ipv4/ipv6: <address> | |
- | | | portid: <> | |
- | | | macaddr: <> for add | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/link | GET | None | |
- | | POST | link_id:<> | |
- | | | state: <1/0> | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/link/<link id> | GET | None | |
- | | POST | ipv4/ipv6: <address> | |
- | | | depth: <> | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/route | GET | None |Displays gateway route entries |
- | | POST | portid: <> |Adds route entries for default gateway |
- | | | nhipv4/nhipv6: <addr> | |
- | | | depth: <> | |
- | | | type:"net/host" | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/rules(vFW/vACL only) | GET | None |Displays the methods /load/clear |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/rules/load | GET | None |Displays if file was loaded |
- | | PUT | <script file | |
- | | | with cmds> |Executes each command from script file |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/rules/clear | GET | None | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/nat(vCGNAPT only) | GET | None |Displays the methods /load/clear |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/nat/load | GET | None |Displays if file was loaded |
- | | PUT | <script file with cmds> | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/config/nat/clear | GET | None | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/log | GET | None |This needs to be implemented for each VNF |
- | | | | just keeping this as placeholder. |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/dbg | GET | None |Will display methods supported like /pipelines/cmd |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/dbg/pipelines | GET | None |Displays pipeline information(names) |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/dbg/pipelines/<pipe id> | GET | None |Displays debug level for particular pipeline |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
- |/vnf/dbg/cmd | GET | None |Last executed command parameters |
- | | POST | cmd: | |
- | | | dbg: | |
- | | | d1: | |
- | | | d2: | |
- +---------------------------------+-----------------+--------------------------+----------------------------------------------------+
-
- PUT/POST - Command success/failure
+==================================
+
+
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| *URI* | *Method* | *Arguments* | *description* |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf* | GET | None | Displays top level methods available |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config* | GET | None | Displays the current config set |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config* | POST | | |
+| | | pci_white_list | |
+| | | num_worker(o) | |
+| | | vnf_type(o) | |
+| | | pkt_type (o) | |
+| | | num_lb(o) | |
+| | | sw_lb(o) | |
+| | | sock_in(o) | |
+| | | hyperthread(o) | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/arp* | GET | None | Displays ARP/ND info |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/arp* | POST | action: <add/del/req> | |
+| | | ipv4/ipv6: <address> | |
+| | | portid: <> | |
+| | | macaddr: <> for add | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/link* | GET | None | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/link* | POST | link_id:<> | |
+| | | state: <1/0> | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/link/<link id>* | GET | None | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/link/<link id>* | POST | ipv4/ipv6: <address> | |
+| | | depth: <> | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/route* | GET | None | Displays gateway route entries |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/route* | POST | portid: <> | Adds route entries for default gateway |
+| | | nhipv4/nhipv6: <addr> | |
+| | | depth: <> | |
+| | | type:"net/host" | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/rules(vFW/vACL)* | GET | None | Displays the methods /load/clear |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/rules/load* | GET | None | Displays if file was loaded |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/rules/load* | PUT | <script file | |
+| | | with cmds> | Executes each command from script file |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/rules/clear* | GET | None | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/nat(vCGNAPT only)* | GET | None | Displays the methods /load/clear |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/nat/load* | GET | None | Displays if file was loaded |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/rules/load* | PUT | <script file with cmds> | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/config/nat/clear* | GET | None | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/log* | GET | None | This needs to be implemented for each VNF |
+| | | | just keeping this as placeholder. |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/dbg* | GET | None | Will display methods supported like /pipelines/cmd |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/dbg/pipelines* | GET | None | Displays pipeline information(names) |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/dbg/pipelines/<pipe id>* | GET | None | Displays debug level for particular pipeline |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/dbg/cmd* | GET | None | Last executed command parameters |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+| */vnf/dbg/cmd* | POST | cmd: | |
+| | | dbg: | |
+| | | d1: | |
+| | | d2: | |
++---------------------------------+-----------+--------------------------+----------------------------------------------------+
+
+ PUT/POST - Command success/failure
API Usage
-===============
+---------
-1. Run time Usage
-====================
+Run time Usage
+^^^^^^^^^^^^^^
An application(say vFW) with REST API support is run as follows
with just PORT MASK as input. The following environment variables
need to be set before launching the application(To be run from
samplevnf directory).
-::
- ./build/vFW (Without the -f & -s option)
+ ::
+ ./build/vFW (Without the -f & -s option)
1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the /vnf/config REST method.
-
- ::
+ ::
e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:08:00.0 0000:08:00.1"}' http://<IP>/vnf/config
Note: the config is mostly implemented based on existing VNF's. if new parameters
@@ -170,7 +179,6 @@ samplevnf directory).
"public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config
2. Check the Link IP's using the REST API (vCGNAPT/vACL/vFW)
-
::
e.g curl <IP>/vnf/config/link
@@ -183,7 +191,6 @@ samplevnf directory).
http://<IP>/vnf/config/link
3. Now that links are enabled we can configure IP's using link method as follows (vCGNAPT/vACL/vFW)
-
::
e.g curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}'
http://<IP>/vnf/config/link/0