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 - Readme
   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
  69 VNF Application init()
  70 =========================
  71
  72 Initialize the civetweb library
  73 ================================
  74
  75 mg_init_library(0);
  76
  77 Start the web server
  78 =====================
  79 ctx = mg_start(NULL, 0, options);
  80
  81
  82 Once the civetweb server is started we can register our URI’s as show below
  83 mg_set_request_handler(ctx, "/config", static_cfg_handler, 0);
  84
  85 In the above example “/config” is the URI & static_cfg_handler() is
  86 the handler that gets called when a user invokes this URI through
  87 the HTTP client. API's have been mostly implemented for existing VNF's
  88 like vCGNAPT, vFW & vACL. you might want to implement custom handlers
  89 for your VNF.
  90
  91 URI definition for different VNF’s
  92 ===================================
  93
  94
  95 URI                                     REST Method          Arguments                  Description
  96 ===========================================================================================================================
  97 /vnf                                    GET                     None                    Displays top level methods available
  98
  99 /vnf/config                             GET                     None                    Displays the current config set
 100                                         POST                    pci_white_list:         Command success/failure
 101                                                                 num_worker(o):
 102                                                                 vnf_type(o):
 103                                                                 pkt_type (o):
 104                                                                 num_lb(o):
 105                                                                 sw_lb(o):
 106                                                                 sock_in(o):
 107                                                                 hyperthread(o) :
 108
 109 /vnf/config/arp                         GET                     None                    Displays ARP/ND info
 110                                         POST                    action: <add/del/req>   Command success/failure
 111                                                                 ipv4/ipv6: <address>
 112                                                                 portid: <>
 113                                                                 macaddr: <> for add
 114
 115 /vnf/config/link                        GET                     None
 116                                         POST                    link_id:<>              Command success/failure
 117                                                                 state: <1/0>
 118
 119 /vnf/config/link/<link id>              GET                     None
 120                                         POST                    ipv4/ipv6: <address>    Command success/failure
 121                                                                 depth: <>
 122
 123
 124 /vnf/config/route                       GET                     None                    Displays gateway route entries
 125                                         POST                    portid: <>              Adds route entries for default gateway
 126                                                                 nhipv4/nhipv6: <addr>
 127                                                                 depth: <>
 128                                                                 type:"net/host"
 129
 130 /vnf/config/rules(vFW/vACL only)        GET                     None                    Displays the methods /load/clear
 131 /vnf/config/rules/load                  GET                     None                    Displays if file was loaded
 132                                         PUT                     <script file
 133                                                                 with cmds>              Executes each command from script file
 134 /vnf/config/rules/clear                 GET                     None                    Command success/failure clear the stat
 135
 136 /vnf/config/nat(vCGNAPT only)           GET                     None                    Displays the methods /load/clear
 137 /vnf/config/nat/load                    GET                     None                    Displays if file was loaded
 138                                         PUT                     <script file
 139                                                                  with commands>         Executes each command from script file
 140
 141 /vnf/config/nat/clear                   GET                     None                    Command success/failure clear the stats
 142 /vnf/log                                GET                     None                    This needs to be implemented for each VNF
 143                                                                                         just keeping this as placeholder.
 144
 145 /vnf/dbg                                GET                     None                    Will display methods supported like /pipelines/cmd
 146 /vnf/dbg/pipelines                      GET                     None                    Displays pipeline information(names)
 147                                                                                         of each pipelines
 148 /vnf/dbg/pipelines/<pipe id>            GET                     None                    Displays debug level for particular pipeline
 149
 150 /vnf/dbg/cmd                            GET                     None                    Last executed command parameters
 151                                         POST                    cmd:                    Command success/failure
 152                                                                 dbg:
 153                                                                 d1:
 154                                                                 d2:
 155
 156 API Usage
 157 ===============
 158
 159 1. Initialization
 160 ================
 161
 162 In order to integrate to your VNF these are the steps required
 163
 164 In your VNF application init
 165
 166
 167 #ifdef REST_API_SUPPORT
 168         Initialize the rest api
 169         struct mg_context *ctx = rest_api_init(&app);
 170 #endif
 171
 172
 173 #ifdef REST_API_SUPPORT
 174         rest api's for cgnapt
 175         rest_api_<vnf>_init(ctx, &app);
 176 #endif
 177
 178
 179 void rest_api_<vnf>_init(struct mg_context *ctx, struct app_params *app)
 180 {
 181         myapp = app;
 182
 183         VNF specific command registration
 184         mg_set_request_handler(,,,);
 185
 186 }
 187
 188
 189 2. Run time Usage
 190 ====================
 191
 192 An application(say vFW) with REST API support is run as follows
 193 with just PORT MASK as input. The following environment variables
 194 need to be set before launching the application(To be run from
 195 samplevnf directory).
 196
 197 export VNF_CORE=`pwd`
 198 export RTE_SDK=`pwd`/dpdk-16.04
 199 export RTE_TARGET=x86_64-native-linuxapp-gcc
 200
 201 ./build/vFW (Without the -f & -s option)
 202
 203 1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the
 204 /vnf/config REST method. A typical curl command if used will look like below
 205 shown. This with minimal parameter. For more options please refer to above REST
 206 methods table.
 207
 208 e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:08:00.0
 209  0000:08:00.1"}' http://<IP>/vnf/config
 210
 211 Note: the config is mostly implemented based on existing VNF's. if new parameters
 212 are required in the config we need to add that as part of the vnf_template.
 213
 214 Once the config is provided the application gets launched.
 215
 216 Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives
 217 a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple
 218 public_ip_port_range being added, please note the "/" being used to seperate multiple
 219 inputs for public_ip_port_range.
 220
 221 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",
 222                 "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)",
 223                 "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config
 224
 225 2. Check the Link IP's using the REST API (vCGNAPT/vACL/vFW)
 226 e.g curl <IP>/vnf/config/link
 227
 228 This would indicate the number of links enabled. You should enable all the links
 229 by using following curl command for links 0 & 1
 230
 231 e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}'
 232 http://<IP>/vnf/config/link
 233 curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}'
 234 http://<IP>/vnf/config/link
 235
 236 3. Now that links are enabled we can configure IP's using link method as follows (vCGNAPT/vACL/vFW)
 237
 238 e.g  curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}'
 239 http://<IP>/vnf/config/link/0
 240 curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}'
 241 http://<IP>/vnf/config/link/1
 242
 243 Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports
 244 required.
 245 /vnf/config/route
 246
 247 curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address",
 248  "depth":"8", "type":"net"}' http://<IP>/vnf/config/route
 249
 250 4. Adding arp entries we can use this method (vCGNAPT/vACL/vFW)
 251 /vnf/config/arp
 252
 253 e.g
 254
 255 curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20",
 256                  "portid":"0", "macaddr":"00:00:00:00:00:01"}'
 257                  http://10.223.166.213/vnf/config/arp
 258
 259 curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"172.16.40.20",
 260                  "portid":"1", "macaddr":"00:00:00:00:00:02"}'
 261                  http://10.223.166.213/vnf/config/arp
 262
 263 5. Adding route entries we can use this method (vCGNAPT/vACL/vFW)
 264 vnf/config/route
 265
 266 e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20",
 267                   "portid":"0"}' http://10.223.166.240/vnf/config/route
 268 curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":8", "nhipv4":"172.16.100.20",
 269                  "portid":"1"}' http://10.223.166.240/vnf/config/route
 270
 271 5. In order to load the rules a script file needs to be posting a script.(vACL/vFW)
 272 /vnf/config/rules/load
 273
 274 Typical example for loading a script file is shown below
 275 curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load
 276
 277 typically arpadd/routeadd commands can be provided as part of this to
 278 add static arp entries & adding route entries providing the NHIP's.
 279
 280 6. The following REST api's for runtime configuring through a script (vCGNAPT Only)
 281 /vnf/config/rules/clear
 282 /vnf/config/nat
 283 /vnf/config/nat/load
 284
 285 7. For debug purpose following REST API's could be used as described above.(vCGNAPT/vACL/vFW)
 286
 287 /vnf/dbg
 288
 289 e.g curl http://10.223.166.240/vnf/config/dbg
 290
 291 /vnf/dbg/pipelines
 292 e.g curl http://10.223.166.240/vnf/config/dbg/pipelines
 293
 294 /vnf/dbg/pipelines/<pipe id>
 295 e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id>
 296
 297 /vnf/dbg/cmd
 298
 299 8. For stats we can use the following method (vCGNAPT/vACL/vFW)
 300
 301 /vnf/stats
 302 e.g curl <IP>/vnf/stats
 303
 304 9. For quittiong the application (vCGNAPT/vACL/vFW)
 305 /vnf/quit
 306
 307 e.g curl <IP>/vnf/quit