Home > vSphere API > Two Important Tips Reading vSphere API Reference

Two Important Tips Reading vSphere API Reference

September 29th, 2010 Leave a comment Go to comments

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.

Time to learn how to "Google" and manage your VMware and clouds in a fast and secure


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.

  1. Vishal
    October 1st, 2010 at 12:54 | #1


    can you make the Event Object implement Serializable, we are internally using these event objects on our JMS bus, and those objects must be Serializable, So to solve it we are right now converting all of event content to local Serializable objects. and publishing them.

  2. October 1st, 2010 at 14:25 | #2

    Hi Vishal,

    Please file a feature request from the vijava tracker: https://sourceforge.net/tracker/?group_id=228007. I will get to it later.


  3. October 5th, 2010 at 11:26 | #3

    Steve, thanks a lot for explaining the answer (http://communities.vmware.com/message/1615618#1615618) further via this post. Points understood.

    But can’t VMWare document all the scenarios for the * for each field in the SDK documentation? e.g. writing that a property is available in vCenter and not in ESX just like they do for the performance counters documentation.

  4. October 5th, 2010 at 18:59 | #4

    Hi Monis,

    Thanks for your feedback. I think it’s a great idea on detailing the * in the SDK documentation.


  1. No trackbacks yet.