API Versioning

As of release 17.1, Avi Vantage supports API versioning for backward compatibility with automation scripts written for an object model older than the current one. Such scripts need not be updated to keep up with object model changes.

This feature requires X-Avi-Version in the request header. For backward compatibility, if X-Avi-Version is not specified, the Avi Controller defaults to API version 16.4.1. When automation scripts leverage features introduced in an API version other than 16.4.1, X-Avi-Version must be set correctly to ensure proper operation. If the incoming request header has X-Avi-Version set lower than the current version of the Controller, the incoming request payload is passed through a series of forward migration routines (similar to the upgrade workflow) to make it compatible with the current version’s object model. Similarly, the response payload is also passed through a series of reverse migration routines to make it compatible with the object model expected by the caller.

Examples

In the first code sequence below, X-Avi-Version is not specified, so the Controller defaults to API version 16.4.1. Data in both the request and the response will be in the API version 16.4.1 VirtualService object model, even though the Controller is running 17.1.

session = ApiSession('10.10.24.52', 'admin', 'avi123')
In [8]: data = {'name':'vs1', 'services':{'port':80}, "ip_address":{'addr':'1.1.1.1', 'type':'V4'}}

In [9]: session.post('virtualservice', data=data).json()
/usr/local/lib/python2.7/dist-packages/requests/packages/urllib3/connectionpool.py:789: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.org/en/latest/security.html
  InsecureRequestWarning)
Out[9]:
{u'_last_modified': u'1491675534346545',
 u'active_standby_se_tag': u'ACTIVE_STANDBY_SE_1',
 u'analytics_profile_ref': u'https://10.10.24.52/api/analyticsprofile/analyticsprofile-399ea5d3-0fc7-4b5d-bc9f-3a4d610dc938#System-Analytics-Profile',
 u'application_profile_ref': u'https://10.10.24.52/api/applicationprofile/applicationprofile-84b9e8a1-f91a-4182-9477-f5955ac4fcf0#System-HTTP',
 u'auto_allocate_floating_ip': False,
 u'auto_allocate_ip': False,
 u'avi_allocated_fip': False,
 u'avi_allocated_vip': False,
 u'cloud_ref': u'https://10.10.24.52/api/cloud/cloud-6ffb903b-bde1-4b73-a028-b53b0584d6b1#Default-Cloud',
 u'cloud_type': u'CLOUD_NONE',
 u'delay_fairness': False,
 u'east_west_placement': False,
 u'enable_autogw': True,
 u'enabled': True,
 u'flow_dist': u'LOAD_AWARE',
 u'flow_label_type': u'NO_LABEL',
 u'ign_pool_net_reach': False,
 u'ip_address': {u'addr': u'1.1.1.1', u'type': u'V4'},
 u'limit_doser': False,
 u'max_cps_per_client': 0,
 u'name': u'vs1',
 u'network_profile_ref': u'https://10.10.24.52/api/networkprofile/networkprofile-d93b4ed2-f3a5-49d3-888f-870df9296078#System-TCP-Proxy',
 u'remove_listening_port_on_vs_down': False,
 u'scaleout_ecmp': False,
 u'se_group_ref': u'https://10.10.24.52/api/serviceenginegroup/serviceenginegroup-b64820d7-2a15-4808-b1c8-8009f0f10f2b#Default-Group',
 u'services': [{u'enable_ssl': False, u'port': 80, u'port_range_end': 80}],
 u'ssl_sess_cache_avg_size': 1024,
 u'tenant_ref': u'https://10.10.24.52/api/tenant/admin#admin',
 u'type': u'VS_TYPE_NORMAL',
 u'url': u'https://10.10.24.52/api/virtualservice/virtualservice-88dc2eed-bfc2-42eb-bc97-d3e8001ce853#vs1',
 u'use_bridge_ip_as_vip': False,
 u'uuid': u'virtualservice-88dc2eed-bfc2-42eb-bc97-d3e8001ce853',
 u'vrf_context_ref': u'https://10.10.24.52/api/vrfcontext/vrfcontext-62750958-d699-43d9-930c-f27b602726a6#global',
 u'weight': 1}

Users choosing to use the new object model to create a VirtualService object with multiple VIPs (a feature introduced in 17.1), can do so as follows:


session = ApiSession('10.10.24.52', 'admin', 'avi123', api_version='17.1')
In [15]: new_data = {'name':'vs1', 'services':{'port':80}, 'vip':{"ip_address":{'addr':'1.1.1.1', 'type':'V4'}}}

In [16]: session.post('virtualservice', data=new_data).json()
/usr/local/lib/python2.7/dist-packages/requests/packages/urllib3/connectionpool.py:789: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.org/en/latest/security.html
  InsecureRequestWarning)
Out[16]:
{u'_last_modified': u'1491677570952612',
 u'active_standby_se_tag': u'ACTIVE_STANDBY_SE_1',
 u'analytics_profile_ref': u'https://10.10.24.52/api/analyticsprofile/analyticsprofile-399ea5d3-0fc7-4b5d-bc9f-3a4d610dc938#System-Analytics-Profile',
 u'application_profile_ref': u'https://10.10.24.52/api/applicationprofile/applicationprofile-84b9e8a1-f91a-4182-9477-f5955ac4fcf0#System-HTTP',
 u'cloud_ref': u'https://10.10.24.52/api/cloud/cloud-6ffb903b-bde1-4b73-a028-b53b0584d6b1#Default-Cloud',
 u'cloud_type': u'CLOUD_NONE',
 u'delay_fairness': False,
 u'east_west_placement': False,
 u'enable_autogw': True,
 u'enabled': True,
 u'flow_dist': u'LOAD_AWARE',
 u'flow_label_type': u'NO_LABEL',
 u'ign_pool_net_reach': False,
 u'limit_doser': False,
 u'max_cps_per_client': 0,
 u'name': u'vs1',
 u'network_profile_ref': u'https://10.10.24.52/api/networkprofile/networkprofile-d93b4ed2-f3a5-49d3-888f-870df9296078#System-TCP-Proxy',
 u'remove_listening_port_on_vs_down': False,
 u'scaleout_ecmp': False,
 u'se_group_ref': u'https://10.10.24.52/api/serviceenginegroup/serviceenginegroup-b64820d7-2a15-4808-b1c8-8009f0f10f2b#Default-Group',
 u'services': [{u'enable_ssl': False, u'port': 80, u'port_range_end': 80}],
 u'ssl_sess_cache_avg_size': 1024,
 u'tenant_ref': u'https://10.10.24.52/api/tenant/admin#admin',
 u'type': u'VS_TYPE_NORMAL',
 u'url': u'https://10.10.24.52/api/virtualservice/virtualservice-71066ce8-67fd-4d23-a080-951f133a83a9#vs1',
 u'use_bridge_ip_as_vip': False,
 u'uuid': u'virtualservice-71066ce8-67fd-4d23-a080-951f133a83a9',
 u'vip': [{u'auto_allocate_floating_ip': False,
   u'auto_allocate_ip': False,
   u'avi_allocated_fip': False,
   u'avi_allocated_vip': False,
   u'enabled': True,
   u'ip_address': {u'addr': u'1.1.1.1', u'type': u'V4'},
   u'vip_id': u'0'}],
 u'vrf_context_ref': u'https://10.10.24.52/api/vrfcontext/vrfcontext-62750958-d699-43d9-930c-f27b602726a6#global',
 u'weight': 1}