Home > vSphere API > Top 5 Myths about VMware vSphere API

Top 5 Myths about VMware vSphere API

February 28th, 2010 Leave a comment Go to comments

If you have trouble to understand vSphere API when you first use it, you are definitely not alone. I had the same trouble when I first used it a while back.

Some of the troubles come from the disconnect between conventional programming model and that of vSphere API. In this blog, I summarize the top 5 myths about vSphere API based on my experience and the questions I see in the VMware community forum and vSphere Java API forum:

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

  1. Non-existing Managed Objects
  2. Pervasive PropertyCollector
  3. Short-Lived Task Object
  4. “Weak” HostSystem
  5. “Un-documented” View

Let’s examine each of them one by one.

Non-existing Managed Objects

People talk about managed objects all the time, but you don’t see any of them while coding with Web Service SDK. There is a disconnect between Web Services API and the API Reference. On one hand, the API Reference has nice descriptions of all managed objects; on the other side, you don’t find any of them in any of the sample code.

Well, by nature Web Services is procedural and it does not support OO directly. All the methods of all the managed objects are flattened out into a single jumbo interface. To identify the managed object, a ManagedObjectReference is added as the first parameter. You can find the same idea when you want to emulate OO programming in C.

Open source vSphere Java API re-constructs all the managed objects, therefore you can find them and take advantage of real OOP besides huge performance gain.

Pervasive PropertyCollector

If you have ever read or written any code with vSphere Web Services, you must know PropertyCollector to some extent. It’s a powerful managed object that is used to get properties from the server side.

It’s very powerful yet very hard to use. The related code is too long for its purpose. To get a simple property out of the server, you may end up at least 20 lines of code. Although most people don’t like it, but cannot get away from it because it’s the only way to get any properties of any managed objects.

Beyond the basis property retrieval, the property collector supports advance features like object traversal which allows you to define paths to search for objects, and change notification which pushes the changes from the server to the registered clients.

To simplify this, vSphere Java API adds getter methods for every property. So the complexity is removed totally. You can still use the collector for advanced features.

Short-Lived Task Object

Task is returned from a asynchronous call (with a name pattern *_Task), so that the client can still track the progress of a un-finished work. There are many questions related to this, for example, the property cannot be retrieved. 9 out 10 times, it’s related to the fact that it’s retrieved a little while after the task is finished. By default a task only lives for about 10 minutes after which you cannot do anything with it, even though you still have the handle (ManagedObjectReference) to it.

You have to use TaskHistoryCollector to retrieve the finished tasks.

“Weak” HostSystem

Compared to other managed entities like VirtualMachine, you may find the HostSystem is weak in that you can’t do much with it. But it corresponds to the hypervisor which is the critical part in the virtualization kingdom.

It turns out that there are so much to do with the hypervisor that the functionalities are divided and delegated to other attached managed objects, like HostNetworkSystem. These managed objects has a naming pattern, all starts with Host*. If you have trouble to find a right method in HostSystem, try these Host* types.

“Un-documented” View

The View family of managed objects were originally designed for vSphere Client. It allows the Client to specify what managed objects to watch based on their visibility. You don’t want to get notified about a change of virtual machine that is invisible to the user.

If you look at the official programming guide and samples, there is nothing about this. The API reference has nice descriptions on each of the types. Without a sample showing how they work together, it’s hard to get started. If you are developing a GUI application, you may want to follow the footsteps of VMware.

There may be more myths while you learning the vSphere API. Please feel free to share them here. I can change the title to Top X myths later on. :-)

  1. February 28th, 2010 at 23:58 | #1


    Another great solid post! This is definitely a good article for those that are looking at programming/scripting against the vSphere APIs. I’ve always wondered about the “Views” but never looked too deep, I had a feeling that it might have been related for creating GUI application with the vSphere API, similar to db view.

    Keep up the great posts!


  2. March 1st, 2010 at 02:09 | #2

    Thanks William!

    The vSphere APIs has indeed packed many functionalities, therefore too broad to master in short time. The “Views” is especially complicated, not only because it’s not documented, but also because it can easily be confused with View in VI Perl and VI .Net (the one behind the PowerCLI).

    Please keep the comments coming!


  3. March 1st, 2010 at 22:38 | #3


    Since “Views” are complicated, perhaps it might be a good topic for a blog post :) Maybe going over how one might make use of views and maybe some best practices around.



  4. March 1st, 2010 at 22:54 | #4

    Great idea. I will write about it soon. Stay tuned. Thanks!


  5. March 3rd, 2010 at 09:46 | #5

    Isn’t it a view just a filter specification for all properties of a particular object/hierarchy and its descendants?

  6. March 3rd, 2010 at 10:39 | #6

    The “View” in vSphere API is a family of managed objects. In VI Perl, the view is more like what you just mentioned. As William suggested, I will write a blog on this topic soon.


  7. March 24th, 2010 at 18:10 | #7


    Very nice post. I’m new to the VMWare API and you’re absolutely correct in saying it’s a different mindset! I was wondering if you had any recommendations on how to use the API to retrieve a complete inventory of an ESX or vSphere server including the hierarchy? Basically, trying to create an XML file with nodes and their relations. Any thoughts would be wonderful.


  8. March 24th, 2010 at 23:15 | #8

    Hi Mark,

    I am glad you like this post. You will get used to the vSphere API after a little while, especially if you use VI Java API.

    The VI Java API has a helper class called InventoryNavigator which can get all the managed entities in the inventory in one call. The returned objects are all flattened out and you have to reconstruct the hierarchy by yourself.

    The other alternative is to start from the rootFolder and dig down to its child nodes and sub child nodes by yourself. Be careful with the recursion because objects like folders could have other folders as child nodes for unlimited depth (in theory).

    There is actually one more with the client REST API included in vi java 2.0. I have a blog on how to use it. Just do a search.

    Good luck!


  9. Watsh Rajneesh
    December 12th, 2011 at 20:16 | #9

    Hi Steve,

    Is there a way to collect the inventory with least hit to the vCenter server? My main concern here is using InventoryNavigator and then reconstructing the hierarchy makes too many round-trips to the vCenter server for every attribute in a Managed Object. Like HostSystem.getName() also results in a network roundtrip. Is there an API in vijava that could give me the full managed object with its properties saved locally rather than getting it each time from server? Or should i just use the PropertyCollector directly to get all the objects with their properties? Please advice.


  10. December 12th, 2011 at 21:01 | #10

    You may want to take a look at the caching framework which was discussed in a article in this blog.

  1. March 23rd, 2010 at 00:03 | #1