docs/testing/user/userguide/06-How_to_use_REST_api.rst

   1 .. This work is licensed under a creative commons attribution 4.0 international
   2 .. license.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) opnfv, national center of scientific research "demokritos" and others.
   5
   6 ========
   7 REST API
   8 ========
   9
  10 Introduction
  11 ------------
  12 As the internet industry progresses creating REST API becomes more concrete
  13 with emerging best Practices. RESTful web services don’t follow a prescribed
  14 standard except fpr the protocol that is used which is HTTP, its important
  15 to build RESTful API in accordance with industry best practices to ease
  16 development & increase client adoption.
  17
  18 In REST Architecture everything is a resource. RESTful web services are light
  19 weight, highly scalable and maintainable and are very commonly used to
  20 create APIs for web-based applications.
  21
  22 Here are important points to be considered:
  23
  24  * GET operations are read only and are safe.
  25  * PUT and DELETE operations are idempotent means their result will
  26    always same no matter how many times these operations are invoked.
  27  * PUT and POST operation are nearly same with the difference lying
  28    only in the result where PUT operation is idempotent and POST
  29    operation can cause different result.
  30
  31
  32 REST API in SampleVNF
  33 ---------------------
  34
  35 In SampleVNF project VNF’s are run under different contexts like BareMetal,
  36 SRIOV, OVS & Openstack etc. It becomes difficult to interact with the
  37 VNF’s using the command line interface provided by the VNF’s currently.
  38
  39 Hence there is a need to provide a web interface to the VNF’s running in
  40 different environments through the REST api’s. REST can be used to modify
  41 or view resources on the server without performing any server-side
  42 operations.
  43
  44 REST api on VNF’s will help adapting with the new automation techniques
  45 being adapted in yardstick.
  46
  47 Web server integration with VNF’s
  48 ---------------------------------
  49
  50 In order to implement REST api’s in VNF one of the first task is to
  51 identify a simple web server that needs to be integrated with VNF’s.
  52 For this purpose “civetweb” is identified as the web server That will
  53 be integrated with the VNF application.
  54
  55 CivetWeb is an easy to use, powerful, C/C++ embeddable web server with
  56 optional CGI, SSL and Lua support. CivetWeb can be used by developers
  57 as a library, to add web server functionality to an existing application.
  58
  59 Civetweb is a project forked out of Mongoose. CivetWeb uses an [MITlicense].
  60 It can also be used by end users as a stand-alone web server. It is available
  61 as single executable, no installation is required.
  62
  63 In our project we will be integrating civetweb into each of our VNF’s.
  64 Civetweb exposes a few functions which are used to resgister custom handlers
  65 for different URI’s that are implemented.
  66 Typical usage is shown below
  67
  68 URI definition for different VNF’s
  69 ==================================
  70
  71
  72 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  73 | *URI*                           |  *Method* |    *Arguments*           |   *description*                                    |
  74 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  75 | */vnf*                          |   GET     | None                     |  Displays top level methods available              |
  76 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  77 | */vnf/config*                   |   GET     | None                     |  Displays the current config set                   |
  78 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  79 | */vnf/config*                   |   POST    |                          |                                                    |
  80 |                                 |           | pci_white_list           |                                                    |
  81 |                                 |           |   num_worker(o)          |                                                    |
  82 |                                 |           |   vnf_type(o)            |                                                    |
  83 |                                 |           |   pkt_type (o)           |                                                    |
  84 |                                 |           |   num_lb(o)              |                                                    |
  85 |                                 |           |   sw_lb(o)               |                                                    |
  86 |                                 |           |   sock_in(o)             |                                                    |
  87 |                                 |           |   hyperthread(o)         |                                                    |
  88 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  89 | */vnf/config/arp*               |   GET     |  None                    | Displays ARP/ND info                               |
  90 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  91 | */vnf/config/arp*               |   POST    |  action: <add/del/req>   |                                                    |
  92 |                                 |           |    ipv4/ipv6: <address>  |                                                    |
  93 |                                 |           |    portid: <>            |                                                    |
  94 |                                 |           |    macaddr: <> for add   |                                                    |
  95 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  96 | */vnf/config/link*              |   GET     |  None                    |                                                    |
  97 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
  98 | */vnf/config/link*              |   POST    |  link_id:<>              |                                                    |
  99 |                                 |           |  state: <1/0>            |                                                    |
 100 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 101 | */vnf/config/link/<link id>*    |   GET     |  None                    |                                                    |
 102 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 103 | */vnf/config/link/<link id>*    |   POST    |  ipv4/ipv6: <address>    |                                                    |
 104 |                                 |           |  depth: <>               |                                                    |
 105 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 106 | */vnf/config/route*             |   GET     |  None                    | Displays gateway route entries                     |
 107 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 108 | */vnf/config/route*             |   POST    |  portid: <>              | Adds route entries for default gateway             |
 109 |                                 |           |  nhipv4/nhipv6: <addr>   |                                                    |
 110 |                                 |           |  depth: <>               |                                                    |
 111 |                                 |           |  type:"net/host"         |                                                    |
 112 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 113 | */vnf/config/rules(vFW/vACL)*   |   GET     |  None                    | Displays the methods /load/clear                   |
 114 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 115 | */vnf/config/rules/load*        |   GET     |  None                    | Displays if file was loaded                        |
 116 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 117 | */vnf/config/rules/load*        |   PUT     |  <script file            |                                                    |
 118 |                                 |           |  with cmds>              | Executes each command from script file             |
 119 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 120 | */vnf/config/rules/clear*       |   GET     |  None                    |                                                    |
 121 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 122 | */vnf/config/nat(vCGNAPT only)* |   GET     |  None                    | Displays the methods /load/clear                   |
 123 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 124 | */vnf/config/nat/load*          |   GET     |  None                    | Displays if file was loaded                        |
 125 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 126 | */vnf/config/rules/load*        |   PUT     |  <script file with cmds> |                                                    |
 127 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 128 | */vnf/config/nat/clear*         |   GET     |  None                    |                                                    |
 129 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 130 | */vnf/log*                      |   GET     |  None                    | This needs to be implemented for each VNF          |
 131 |                                 |           |                          |          just keeping this as placeholder.         |
 132 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 133 | */vnf/dbg*                      |   GET     |  None                    | Will display methods supported like /pipelines/cmd |
 134 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 135 | */vnf/dbg/pipelines*            |   GET     |  None                    | Displays pipeline information(names)               |
 136 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 137 | */vnf/dbg/pipelines/<pipe id>*  |   GET     |  None                    | Displays debug level for particular pipeline       |
 138 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 139 | */vnf/dbg/cmd*                  |   GET     |  None                    | Last executed command parameters                   |
 140 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 141 | */vnf/dbg/cmd*                  |   POST    |  cmd:                    |                                                    |
 142 |                                 |           |    dbg:                  |                                                    |
 143 |                                 |           |    d1:                   |                                                    |
 144 |                                 |           |    d2:                   |                                                    |
 145 +---------------------------------+-----------+--------------------------+----------------------------------------------------+
 146
 147    PUT/POST - Command success/failure
 148
 149 API Usage
 150 ---------
 151
 152 Run time Usage
 153 ==============
 154
 155 An application(say vFW) with REST API support is run as follows
 156 with just PORT MASK as input. The following environment variables
 157 need to be set before launching the application(To be run from
 158 samplevnf directory).
 159
 160    ::
 161
 162      ./build/vFW (Without the -f & -s option)
 163
 164 1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the /vnf/config REST method.
 165    ::
 166
 167     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
 168
 169     Note: the config is mostly implemented based on existing VNF's. if new parameters
 170           are required in the config we need to add that as part of the vnf_template.
 171
 172     Once the config is provided the application gets launched.
 173
 174     Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives
 175     a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple
 176     public_ip_port_range being added, please note the "/" being used to seperate multiple
 177     inputs for public_ip_port_range.
 178
 179     e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:05:00.0 0000:05:00.2 0000:07:00.0 0000:07:00.2",
 180         "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)",
 181         "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config
 182
 183 2. Check the Link IP's using the REST API (vCGNAPT/vACL/vFW)
 184    ::
 185
 186      e.g curl <IP>/vnf/config/link
 187
 188      This would indicate the number of links enabled. You should enable all the links
 189      by using following curl command for links 0 & 1
 190
 191      e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}'
 192      http://<IP>/vnf/config/link
 193      curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}'
 194      http://<IP>/vnf/config/link
 195
 196 3. Now that links are enabled we can configure IP's using link method as follows (vCGNAPT/vACL/vFW)
 197    ::
 198
 199      e.g  curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}'
 200      http://<IP>/vnf/config/link/0
 201      curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}'
 202      http://<IP>/vnf/config/link/1
 203
 204      Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports required.
 205      /vnf/config/route
 206
 207      curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address",
 208      "depth":"8", "type":"net"}' http://<IP>/vnf/config/route
 209
 210 4. Adding arp entries we can use this method (vCGNAPT/vACL/vFW)
 211    ::
 212
 213      /vnf/config/arp
 214
 215      e.g
 216      curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20",
 217                  "portid":"0", "macaddr":"00:00:00:00:00:01"}'
 218                  http://10.223.166.213/vnf/config/arp
 219
 220      curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"172.16.40.20",
 221                  "portid":"1", "macaddr":"00:00:00:00:00:02"}'
 222                  http://10.223.166.213/vnf/config/arp
 223
 224 5. Adding route entries we can use this method (vCGNAPT/vACL/vFW)
 225    ::
 226
 227      /vnf/config/route
 228
 229      e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20",
 230                  "portid":"0"}' http://10.223.166.240/vnf/config/route
 231      curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":8", "nhipv4":"172.16.100.20",
 232                  "portid":"1"}' http://10.223.166.240/vnf/config/route
 233
 234 5. In order to load the rules a script file needs to be posting a script.(vACL/vFW)
 235    ::
 236
 237      /vnf/config/rules/load
 238
 239      Typical example for loading a script file is shown below
 240      curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load
 241
 242      typically arpadd/routeadd commands can be provided as part of this to
 243      add static arp entries & adding route entries providing the NHIP's.
 244
 245 6. The following REST api's for runtime configuring through a script (vCGNAPT Only)
 246    ::
 247
 248      /vnf/config/rules/clear
 249      /vnf/config/nat
 250      /vnf/config/nat/load
 251
 252 7. For debug purpose following REST API's could be used as described above.(vCGNAPT/vACL/vFW)
 253    ::
 254
 255      /vnf/dbg
 256      e.g curl http://10.223.166.240/vnf/config/dbg
 257
 258      /vnf/dbg/pipelines
 259      e.g curl http://10.223.166.240/vnf/config/dbg/pipelines
 260
 261      /vnf/dbg/pipelines/<pipe id>
 262      e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id>
 263
 264      /vnf/dbg/cmd
 265
 266 8. For stats we can use the following method (vCGNAPT/vACL/vFW)
 267    ::
 268
 269      /vnf/stats
 270      e.g curl <IP>/vnf/stats
 271
 272 9. For quittiong the application (vCGNAPT/vACL/vFW)
 273    ::
 274
 275      /vnf/quit
 276      e.g curl <IP>/vnf/quit