Two Important Tips Reading vSphere API Reference
Last week I answered a question in VMware Web Services SDK forum about asterisks in vSphere API reference. Underneath these asterisks comes a note saying “May not be present.” What does it really mean?
The asterisks normally show up after properties or sub-properties defined with a managed object. As it says, it’s possible that there is NO value to the property.
Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.
How can it be like this?
There are two major causes. First, it reflects the different implementations of ESX, ESXi and vCenter. As a quick example, you can find many of the properties in the “content” (type: ServiceContent) come with asterisks.
On a vCenter server, you will find values to almost all the properties, but not quite so for ESX/ESXi. But we have one API reference document, so it’s natural to mark whatever possible no value as “may not present.”
Secondly, it may be as such depending on the state of a managed object. For instance, a virtual machine can be a bare machine without an OS installed. Therefore, the “guest” property of the virtual machine could have no value at all.
What does it mean to you?
For one thing, the properties with asterisks may be null. It means you should make sure it’s not null before drilling down the property. I’ve seen many NullPointerException caused by this missed checking.
Yet another type of asterisks
Interestingly, there are another type of asterisks in the APIs with method parameters saying “Need not be set.” As you can guess, the parameter can be null.
But, that is half of the story. The first cause of tip 1 still applies here. Depending on the target server you manage, it could be required. Let’s pick the createVM_Task() method defined in Folder. The host parameter has an asterisk, and for a standalone host or a cluster with DRS you can omit; otherwise it’s a must.
There are also cases where one optional parameter turns required by other parameters. This is one cause that complicates the usage of the API. When you get an InvaidRequest exception, take a look at these parameters that are claimed no need to be set.