Library API Details

Connecting to API server

To make any configuration changes, you first need to connect to API server and get a VNC API handle. This can be done by creating a VncApi object by passing all necessary arguments to its constructor. Example:

vnc_api = VncApi(username='admin', password=<password>, tenant_name='admin',
             api_server_host='', api_server_port='8082',
             api_server_url='/', conf_file=<filename>, user_info=None,
             auth_token=None, auth_host=None, auth_port=None,
             auth_protocol = None, auth_url=None, auth_type=None,
             wait_for_connect=False, api_server_use_ssl=False,


The configuration API library provides a means of accessing and manipulating configuration elements of the system through an object representation. The library API can be classified into two categories:

  • those that manipulate an object locally (client-side)
  • those that reflect/get an object’s content onto/from the configuration API server.

The configuration element types (also referred to as object types) have a hierarchical relationship described in vnc_cfg.xsd schema. The class definitions of all object types are available at vnc_cfg_api_server.gen.resource_common module.

All objects have:
  • a fully-qualified name which is an array of strings representing ancestor names from root

  • an id-perms property which provide unix file-like permissions for the owner, group and others

  • zero or more properties which represent information relevant only to the object

  • zero or more references to other objects

  • zero or more back references from other objects (computed automatically by the server)

  • methods
    • to construct an instance

      >>> example_obj = ExampleType('name', <property_name> = <property_value>)
    • accessors for properties

      >>> print example_obj.get_<property_name>()
      >>> example_obj.set_<property_name>(<property-value>)
    • accessors for referenced objectes

      >>> print example_obj.get_<reference_type>_refs()
      >>> example_obj.add_<reference_type>(reference_obj)
    • getters for back-references (i.e. objects referring to this)

      >>> print example_obj.get_<reference_type>_back_refs()
    • getters for children objects

      >>> print example_obj.get_<child_type>s()

    These methods do not communicate with the API server

The main library class VncApi insert-ref-here has methods for every object type to:

  • create an object

    >>> vnc_lib.example_type_create(example_obj)
  • read an object

    >>> example_obj = vnc_lib.example_type_read(id = <example-uuid>)
    >>> example_obj = vnc_lib.example_type_read(fq_name = ['example-root', ... ,'example-parent', 'example-name'])
  • update an object

    >>> vnc_lib.example_type_update(example_obj)
  • delete an object

    >>> vnc_lib.example_type_delete(id = <example-uuid>)
    >>> vnc_lib.example_type_delete(fq_name = ['example-root', ... ,'example-parent', 'example-name'])
  • list objects (an optional delete=True parameter returns detail instead of summary)

    >>> vnc_lib.example_types_list(parent_id = <parent-uuid>)
    >>> vnc_lib.example_types_list(parent_fq_name = ['example-root', ... ,'example-parent'])
    >>> vnc_lib.example_types_list(obj_uuids = [<example-obj1-uuid>, <example-obj2-uuid>])
    >>> vnc_lib.example_types_list(back_ref_id = <back-ref-uuid>)

These CRUD methods communicate with the API server.

The API server for most objects acts purely as a data store. However properties for some object types are allocated by the API server itself. These include

  • default gateway in case of subnet (if not specified by user)
  • ip address for instance-ip objects (if not specified by user)


Errors from API server (http status codes and response content) are translated to exception objects and raised. The different types of exceptions are defined at cfgm_common.exceptions module


Online documentation of the vnc_api module can be found by:

>>> help(vnc_api)
Help on module vnc_api.vnc_api in vnc_api:
    This is the main module in VNS Config API library. It handles connection to API server,
    exposes configuration elements as objects and allows for manipulating objects locally
    and updating API server
    class VncApi(vnc_api.gen.vnc_api_client_gen.VncApiClientGen)
     |  Method resolution order:
     |      VncApi
     |      vnc_api.gen.vnc_api_client_gen.VncApiClientGen
     |      __builtin__.object
     |  Methods defined here:
     |  __init__(self, username=None, password=None, tenant_name=None, api_server_host=None, api_server_port=None, api_server_url=None)

Online documentation of object methods etc. with standard dir and help python commands

>>> dir(vn_blue_obj)
['__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_type', 'add_network_ipam', 'add_network_policy', 'del_network_ipam', 'del_network_policy', 'dump', 'factory', 'fq_name', 'from_fq_name', 'get_access_control_lists', 'get_floating_ip_pools', 'get_fq_name', 'get_fq_name_str', 'get_id_perms', 'get_instance_ip_back_refs', 'get_network_ipam_refs', 'get_network_policy_refs', 'get_parent_fq_name', 'get_parent_fq_name_str', 'get_project_back_refs', 'get_route_target_list', 'get_routing_instances', 'get_type', 'get_virtual_machine_interface_back_refs', 'name', 'network_ipam_refs', 'network_policy_refs', 'parent_name', 'set_id_perms', 'set_network_ipam', 'set_network_ipam_list', 'set_network_policy', 'set_network_policy_list', 'set_route_target_list', 'uuid']
>>> help(vn_blue_obj)
Help on VirtualNetwork in module vnc_api.gen.resource_common object:
class VirtualNetwork(__builtin__.object)
 |  Represents virtual-network configuration representation.
 |  Child of :class:`.Project` object
 |  Properties of:
 |      * route-target-list (:class:`.RouteTargetList` type)
 |      * id-perms (:class:`.IdPermsType` type)
 |  References to:
 |      * list of (:class:`.NetworkIpam` object, :class:`.VnSubnetsType` attribute)
 |      * list of (:class:`.NetworkPolicy` object, :class:`.VirtualNetworkPolicyType` attribute)
 |  Referred by:
 |      * list of :class:`.Project` objects
 |      * list of :class:`.VirtualMachineInterface` objects
 |      * list of :class:`.InstanceIp` objects

Table Of Contents

Previous topic

REST API Details

Next topic

Library API reference

This Page