Top 10 Best Practices Using VMware VI and vSphere SDK (part 1)

VMware vSphere (as known as VI in earlier versions) SDK includes a comprehensive set of APIs managing the vSphere CloudOS. It can be used to build different types of applications: standalone GUI applications, vSphere Client plug-in, utility tools, Web applications, server applications. It is becoming increasingly important as more and more enterprises become 100% virtualized with vSphere.

This article intends to summarize the best practices for developing applications using VI and vSphere API. I only cover these specific to the applications built on top of VI and vSphere API. The generic best practices for application development are still critical to the success of your project, but not in the scope of this writing.

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.

There are many best practices for each part of the APIs, for example networking, storage, event management, etc. We cannot cover them all here, but pick the top 10 that matter to most developers the most as follows.

#1 Connect to vCenter Server Whenever Possible

There are so many reasons for this to be #1 best practice all in all. This morning I got an email from my colleague who has a client with 10,000 VMs to be managed. They want to collect the performance data of VMs but concern the vMotion. How to track the VMs and get performance data when some of them move from one host to another? The easiest and best way to do it is this #1.
Besides the above, there are several advantages in general:

  • Much more functionalities than ESX or ESXi.
  • Less management with single connection than many sessions to each ESX/ESXi a vCenter manages.
  • Easy tracking of virtual machines when they move around in your virtual data center.
  • Aggregated information only available in vCenter.
  • No worry about the versioning where different ESX/ESXi servers are present. The vCenter takes care of the older versions of hypervisors.
  • There isn’t much performance advantage by connecting to individual hypervisors since 2.5.

#2 Choose the Right APIs

VI SDK 2.5 has 375 methods and 63 managed object types. vSphere addes additional 23 types. There could be more than one way to get things done. You have to think over these while choosing the right API:

  • Synchronous vs Asynchronous
  • Pull vs Push
  • Single vs Batch processing
  • Versioning

Also, you want to avoid Deprecated APIs. The VI and vSphere products evolve over time, so do the APIs. Some of the APIs get deprecated when new releases come out. There won’t be any immediate impact on your application, as the deprecated APIs are still usable. Over the time, these deprecated APIs will gradually phase out. So be proactive in preparing for the changes.

#3 Handle Faults Carefully

VI SDK 2.5 has more than 200 fault types. Each represents a type of failure, and holds information for further analyzing and debugging. Catching the faults makes your application more robust. Note that the intension of RuntimeFault is after the RuntimeException in Java meaning you don’t have to catch it. But at the client side, you do have to catch it as every fault type inherits from RemoteException directly or indirectly.

#4. Collect Only What You Really Need

Over collecting data hurts your performance and put burden on the server. This is especially true when you connect to vCenter which handles a lot of communication, data persistence and management work. Without your API clients, it’s mostly busy already. You don’t want to over burden it and slow down things.

Here is what you can do to restrict the collection:

  • Retrieve only what’s must-to-have, not nice-to-have.
  • Use property path to limit the nested data objects
  • Be conservative with recursion with TravelSpec
  • Collect only once the static data which doesn’t change at all or doesn’t change during a session lifecycle.

# 5 Use PropertyCollector and Task with Extra Caution

The PropertyCollector is a very unique managed object in the SDK. It’s super powerful but also very hard to use. A lot of questions in the community are related to it. The learning curve is pretty high. Even for the experienced developers, it’s fairly easy to be stuck with advanced features like recursive search.

Even so, there is no escape from this PropertyCollector because it’s almost the only way to get properties from any managed object. If you don’t use toolkits as recommended, you have to use the API directly.

Task is another important and commonly used managed object. Quite some (50+) methods return immediately a Task object, using which you can track the progress. A task object has very limited life time with about 10 minutes. After that, you cannot make any call to it directly or indirectly (for example, using the PropertyCollector to get its property). You have to use HistoryCollector for any historical tasks.

Continue next post with #6-10

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


  1. Posted January 29, 2010 at 10:20 am | Permalink

    Steve – thanks for this. As always you hit it right on the head. #4 is one of the common mistakes we see when folks are building monitoring solutions…. Thanks again !

  2. Posted May 29, 2013 at 4:32 am | Permalink

    very good ,sometimes I don’t kown how to choose API objects .any devices?

4 Trackbacks

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>


    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__

    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.