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.

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.

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.

This entry was posted in vSphere API and tagged , , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

4 Comments

  1. Vishal
    Posted October 1, 2010 at 12:54 pm | Permalink

    Steve,

    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. Posted October 1, 2010 at 2:25 pm | Permalink

    Hi Vishal,

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

    Steve

  3. Posted October 5, 2010 at 11:26 am | Permalink

    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. Posted October 5, 2010 at 6:59 pm | Permalink

    Hi Monis,

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

    Steve

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

  • NEED HELP?


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.