.. This work is licensed under a creative commons attribution 4.0 international .. license. .. http://creativecommons.org/licenses/by/4.0 .. (c) opnfv, national center of scientific research "demokritos" and others. ======================================================== REST API - Readme ======================================================== 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 to build RESTful API in accordance with industry best practices to ease development & increase client adoption. In REST Architecture everything is a resource. RESTful web services are light weight, highly scalable and maintainable and are very commonly used to create APIs for web-based applications. Here are important points to be considered: * GET operations are read only and are safe. * PUT and DELETE operations are idempotent means their result will always same no matter how many times these operations are invoked. * PUT and POST operation are nearly same with the difference lying only in the result where PUT operation is idempotent and POST operation can cause different result. 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 VNF’s using the command line interface provided by the VNF’s currently. Hence there is a need to provide a web interface to the VNF’s running in different environments through the REST api’s. REST can be used to modify or view resources on the server without performing any server-side operations. 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. For this purpose “civetweb” is identified as the web server That will be integrated with the VNF application. CivetWeb is an easy to use, powerful, C/C++ embeddable web server with optional CGI, SSL and Lua support. CivetWeb can be used by developers as a library, to add web server functionality to an existing application. Civetweb is a project forked out of Mongoose. CivetWeb uses an [MITlicense]. It can also be used by end users as a stand-alone web server. It is available as single executable, no installation is required. In our project we will be integrating civetweb into each of our VNF’s. Civetweb exposes a few functions which are used to resgister custom handlers for different URI’s that are implemented. Typical usage is shown below VNF Application init() ========================= Initialize the civetweb library ================================ mg_init_library(0); Start the web server ===================== ctx = mg_start(NULL, 0, options); Once the civetweb server is started we can register our URI’s as show below mg_set_request_handler(ctx, "/config", static_cfg_handler, 0); In the above example “/config” is the URI & static_cfg_handler() is the handler that gets called when a user invokes this URI through the HTTP client. API's have been mostly implemented for existing VNF's like vCGNAPT, vFW & vACL. you might want to implement custom handlers for your VNF. 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: Command success/failure 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: Command success/failure ipv4/ipv6:
portid: <> macaddr: <> for add /vnf/config/link GET None POST link_id:<> Command success/failure state: <1/0> /vnf/config/link/ GET None POST ipv4/ipv6:
Command success/failure depth: <> /vnf/config/route GET None Displays gateway route entries POST portid: <> Adds route entries for default gateway nhipv4/nhipv6: 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