Multiple Versions of the vSphere API

When a client application connects to a Web service running on a vSphere server (ESXi or vCenter Server system), the server detects the version of the API that was used to develop the client and makes available only those operations supported by the client.

Client applications convey information about the API version used in the SOAP messages that they send to a vSphere server. These SOAP messages include a versionID in the soapAction attribute. The details are handled transparently by the SOAP toolkit and the client proxy code. The server adjusts its behavior based on the client’s version information, exposing the API version that the client supports to the client.

Starting with vSphere 4.0, information about the supported API versions is contained in an XML file, vimServiceVersions.xml, located on the server (see Service-Versions File (vimServiceVersions.xml)). You can access this file with the URL https://server_hostname/sdk/vimServiceVersions.xml.

Service-Versions File (vimServiceVersions.xml)

<?xml version="1.0" encoding="UTF-8" ?>
- <!--    Copyright 2008-2010 VMware, Inc.  All rights reserved. -->
- <namespaces version="1.0">
     - <namespace>
            <name>urn:vim25</name>
            <version>5.0</version>
     - <priorVersions>
          <version>2.5u2</version>
          <version>2.5</version>
       </priorVersions>
     </namespace>
     - <namespace>
          <name>urn:vim2</name>
          <version>2.0</version>
       </namespace>
  </namespaces>

If you are developing a client application that must support multiple server versions at the same time (ESXi 5.0 and ESXi 5.5, for example), you must obtain information about the API versions that are supported on the server and provide logic in your code to use or not use features, based upon the version information.

One approach to targeting multiple versions of the API from the same client application code is to check for the existence of the server versions file on the server. If you do not find a vimServiceVersions.xml file on the server, the server is older than ESX/ESXi 4.x, vCenter Server 4.x.