Last week an issue was reported with using vSphere SDK 4.1 to connect vSphere 4.0. The problem is related to the HTTP header called “SOAPAction” introduced in vSphere SDK 4.0. A recent KB article introduced this header, but with a minor error. I will talk about it in the end.
With vSphere SDK 4.1, the SOAPAction header has a value of “urn:vim25/4.1” while 4.0 has “urn:vim25/4.0”. For an older version of vSphere server, either vCenter or ESX/ESXi, it has no idea of the new value of SOAPAction, therefore refuse to serve. But the other way around works just fine because the newer version of vSphere knows about the older value but also support the older version of SDK directly. As a result, any application using older version of SDK works with newer version of vSphere. I am not saying your application can leverage new features. In fact, you cannot and must upgrade to do so.
Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.
From the SDK part, I found it’s a little disturbing when your newer SDK cannot work with older vSphere. We all expert newer SDK are better and back compatible. That is why I did something extra in open source VI Java API 2.1 which supports SDK4.1 – make it work with vSphere 4.0 even without your notice. The trick is to initially assume old value of “urn:vim25/4.0” (which works with newer version of vSphere), and then dynamically change it to “urn:vim25/4.1” if the API detects it’s vSphere 4.1. It works pretty well.
Now back to the error of the KB article, it says,
For VMware Infrastructure 3:
<soap:operation soapAction=”” style=”document” />
This is not true. In fact, there was no such header defined or needed. The VI 3.5 does not even check the value, so you can pass any value as you want. The VI Java API 2.1 passes in a value of “urn:vim25/4.0” and works fine when talking to vCenter 2.5/ESX 3.5.
You may wonder, “Why should it be complicated like this?” Well, let me share a bit more history here. In VI API 2.0 and 2.5, we had used the namespace for versioning and got us many troubles. For example, when you generate classes with tools like Apache AXIS, the namespace is mapped to the package name. That is why you see com.vmware.vim and com.vmware.vim25 packages if you worked with these two before. There is nothing wrong with these two package names, but it’s bad when you have to work with two versions of APIs. For most classes, you will have two of them: one in each package and they are exactly the same except the package names. Because of namespace/package issue, VMware started to use HTTP header as a version mechanism in version 4.0.
The open source VI Java API has solved the compatibility problem nicely and supports all the versions of servers from VI 2.0, 2.5, to vSphere 4.0 and 4.1, not to mention other benefits like 10x performance gain, small footprint, and clean license (BSD).
For now, I hope you’ve got the historical background of vSphere API compatibility. If you are interested in more compatibility, you should read my previous posts: Wire Compatibility of Web Services, Why Some vSphere Java API Methods don’t Work with Old Servers? A Story of Compatibility, Tips working with older versions of VMware Infrastructures using VI Java API 2.0