Rest API

The Polycube REST API is implemented in [rest_server.cpp](https://github.com/polycube-network/polycube/blob/master/src/polycubed/src/rest_server.cpp), which defines the main endpoints. This file handles Polycube-wide actions (detailed below), while additional specific endpoints are implemented in each service and are reached through a redirect method.

The REST API starts with the /polycube/v1/ path and can be divided into 8 main parts:

• servicectrls: takes care of everything related to services;

• cubes: deals with everything related to cubes (i.e. an instance of a service);

• netdevs: deals with everything related to network devices (network interfaces);

• version: returns the version of polycubectl;

• connect / disconnect: deals with the connection and disconnection of the ports of two cubes;

• attach / detach: takes care of attaching and detaching a transparent cube (for example the NAT), with a standard cube (for example the Router);

• topology: returns the topology of the running cubes;

• metrics: takes care of returning the metrics in OpenMetrics format of all running cubes.

For all the URLs/endpoints that are not handled directly in the REST server, the redirect method is called which brings to the actual service that implements the requested method. This method comes into play when polycubectl is used to interact with running cubes, for example polycubectl router1 ports ? refers to the endpoint /polycube/v1/router1/ports which is not among the standard ones but is implemented by the router service. In this respect, the main REST server checks if the requested route exists (e.g., the specific service, such as router, exists), then it calls the correct endpoint.

URL	REST SERVER METHOD	HTTP VERB	OUTPUT/DESCRIPTION	POLYCUBECTL COMMAND
/polycube/v1/	root_handler (and also topology, root_help, get_cubes)	OPTIONS	Displays polycubectl commands, available services, running cubes (keyword, type, description)	polycubectl or polycubectl plust the tab key
/polycube/v1/	get_root_handler	GET	It is used for the part of HATEOAS
polycube/v1/services	post_servicectrl	POST	Loads the libpcn-service_name.so service with name given by service_name	polycubectl services add type=lib uri=/absolute/path/to/libpcn-service_name.so name=service_name
polycube/v1/services	get_servicectrls	GET	Displays a list of available services (description, name, pyang_repo_id, servicecontroller, swagger_codegen_repo_id, version)	polycubectl services show
polycube/v1/services/:name	get_servicectrl	GET	Displays the datamodel of the service indicated by the name	polycubectl services show serviceName
polycube/v1/services/:name	delete_servicectrl	DEL	Delete the given service indicated by serviceName	polycubcetl services del serviceName
polycube/v1/cubes	get_cubes	GET	Displays the running cubes with the following information: name, uuid, service-name, type, loglevl, shadow, span	polycubectl cubes
polycube/v1/cubes	post_cubes	POST	Adds N cubes by taking the necessary information from a yaml file	polycubectl cubes add < mycubes.yaml
polycube/v1/cubes	cubes_help	OPTIONS	If there is at least one cube with that name, it displays the name, type and if there is a description	polycubectl cubes ?
polycube/v1/cubes/:cubeName	get_cube	GET	Displays the following information of the cube with that name: name, uuid, service-name, type, loglevl, shadow, span	polycubectl cubes cubeName show
polycube/v1/cubes/:cubeName	cube_help	OPTIONS	Displays what can be done on the cube named cubeName with displaying Keyword, Type, Description	polycubectl cubes cubeName ?
polycube/v1/netdevs	get_netdevs	GET	Displays the name and number of addresses of each network device on the machine	polycubectl netdevs
polycube/v1/netdevs	netdevs_help	OPTIONS	It displays the name, type (netdevs) and if there is a description of each network device on the machine	polycubectl netdevs ?
polycube/v1/netdevs/:name	get_netdev	GET	Displays the name and address number of the network device that matches name	polycubectl netdevs netdevName show
polycube/v1//netdevs/:netdevName	netdev_help	OPTIONS	Displays what can be done on the network device named netdevName by displaying Keyword, Type, Description	polycubectl netdevs netdevName ?
polycube/v1/version	get_version	GET	Displays the version of polycubectl and polycubed	polycubectl version
polycube/v1/connect	connect	POST	Connect two ports of two cubes	polycubcectl connect cube1:port1 cube2:port2
polycube/v1/disconnect	disconnect	POST	Disconnects two ports of two cubes	polycubcectl disconnect cube1:port1 cube2:port2
polycube/v1/connect	connect_help	OPTIONS	If present, it should provide help regarding the connect command	polycubectl connect (plus the tab key)
polycube/v1/attach	attach	POST	Attach a transparent cube to the port of a standard cube	polycubcectl attach trasparenteCube cube1:port1
polycube/v1/detach	detach	POST	Detach a transparent cube from the port of a standard cube	polycubcectl detach trasparenteCube cube1:port1
polycube/v1/topology	topology	GET	Returns the current topology	polycubectl topology
polycube/v1/topology	topology_help	OPTIONS	If present, it should provide help regarding the current topology	polycubectl topology (plus the tab key)
polycube/v1/topology/:ifname	get_if_topology	GET	Displays the cubes to which this interface is attached, both in ingress and egress and also the index of the interface (If ifname is not the name of an interface, display name: ifname)	polycubectl topology show iface (for example enp0s3, which was previously attached to a cube)
polycube/v1/metrics	get_metrics	GET	Displays a list of metrics in OpenMetrics format of all running cubes (of services that have metrics)	no polycubectl command, you can use curl or Prometheus

Example of use

To use Polycube, you go through the REST API and to interact with it you can use polycubectl, curl or even Postman.

After running Polycube with the command sudo polycubed --loglevel=DEBUG, each command is shown with the corresponding (debug) log message, the associated HTTP verb and the endpoint of the REST server being called (only for methods which have as input a Pistache::Rest::Request).

For example:

polycubectl version   # GET : /polycube/v1/version/

polycubectl services show   #  GET : /polycube/v1/services/

polycubectl router r1   # Nothing is displayed, as the message is redirected to the `router` module

polycubectl topology   # GET : /polycube/v1/topology/

polycubectl cubes   # GET : /polycube/v1/cubes/