VMware vSphere API and SDK FAQ

Table Of Content

  1. General
  2. Getting Started
  3. Language Bindings
  4. VI Java API
  5. API Usage
  6. Troubleshooting

Note: your feedbacks and suggestions are important to me. Please feel free to comment here.

[General]

What is VMware vSphere API and vSphere SDK?
VMware vSphere API is a set of interfaces for managing vSphere. You can use the API to do almost all the things the vSphere Client can do. The API is defined as SOAP Web Services with WSDL.
The vSphere SDK is a set of libraries that support vSphere API, as well as tools and samples that assist your development efforts. The vSphere SDK is also known as VI SDK, vCenter SDK, ESX SDK, etc.
In most discussions, the vSphere API and vSphere SDK are used interchangeably.

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.

Who would use and care about the API?
Both system administrators and software developers would be interested in vSphere automation and integration. VMware customers can use it to automate vSphere; partners can use it to integrate with vSphere platform; ISVs can use it build applications.

Is there any formal training on vSphere APIs
Yes, check out vSphere API Training class by the author of VMware VI and vSphere SDK by Prentice Hall, and the creator of the open source vSphere Java API during employment at VMware engineering.

How does vSphere API relate to VI API?
They are essentially the same. VI was renamed as vSphere in its version 4. Accordingly, the API name got changed.

How does vSphere API relate to ESX Agent Manager API?
ESX Agent Manager API is a different set of APIs that help to manage agent VM (think it as driver if hypervisor is OS) across different hosts. It uses same Web Services underlying as vSphere APIs. You can think of it as extension to the vSphere APIs. More info and product support can be found at here.

What releases of vSphere does vSphere API support?
All releases including VI 3.0, VI 3.5, vSphere 4.0, vSphere 4.1, vSphere 5.0, vSphere 5.1, vSphere 5.5, 6.0 as of 2015. Each release of vSphere has a corresponding vSphere APIs.

Where can I get consulting service or vSphere API support?
You can contact DoubleCloud Inc which helps clients on VMware infrastructure automation/orchestration, product integration. You can also buy support and/or commercial product vijavaNG from the company.

Is there commercial license available?
Yes. It’s vijavaNG which has the same interface but much faster and lighter engine, resulting in higher performance and better scalability. The product page is at here.

Does vijavaNG support vSphere 6.0?
Yes. The commercial vijavaNG supports new VMware releases within one week of VMware GA date. For VMware beta customers/partners, early access of vijavaNG is also possible under certain conditions.

Can vSphere API work with VMware Server?
Yes with some versions. All are experimental though.

How does vSphere API relate to vCloud API?
They are designed for different audience in mind. You can think of vSphere API as the under-the-hook API vs. vCloud API as the drive seat API. Functionality wise, vCloud API is, almost, a subset of vSphere API. Format wise, vSphere API is SOAP based while vCloud API is REST based.

Is vSphere API the same as PowerCLI?
No. However, the vSphere PowerCLI is built on top of same vSphere API.

Is there PowerCLI alternative on Linux?
Yes, but not exactly the same level of abstraction. You can try vMA, or leverage VI Java API with JRuby, Jython, etc. Timo Sugliani has created a virtual appliance that can be downloaded here.

Does vSphere API manage solutions like Site Recovery Manager (SRM)?
No. For SRM API, you can check out here.

Can I use vSphere API to execute ESX command?
No. You can however achieve the same or similar result using the vSphere API. Consider SSH if you want to execute commands on ESXi.

Can I use vSphere API for developing vSphere plugins?
Yes. Check out this document I wrote on how to develop a complete vSphere Client plugin with Tomcat and VI Java API at VMware community forum: http://communities.vmware.com/docs/DOC-5881

Can I use vSphere API with Android and iPhone?
Yes. You can find the APIs to make HTTP requests and receive responses.

Can I use vSphere API with Web applications?
Yes. See the vSphere Client plugin.

Where can I find other VMware API ( VMware SDK )?
All the VMware APIs are listed at the VMware developer community.

What if I want to use REST API?
There is no REST API support as of vSphere 4.1. There are however a client side REST API included in vSphere Java API 2.0 and after. For more detail, check it out here.

How to get in-depth tutorial and latest news
The most complete tutorial is the book VMware VI and vSphere SDK written by Steve Jin, the creator of this open source API. To keep updated with the project, subscribe the blog: http://www.doublecloud.org/feed, and follow @sjin2008.

[Getting Started]

Where Should I Get Started?
Before getting started with vSphere API, you should learn the vSphere product first. It should give you basic concepts regarding virtual machine, host, networking, storage, etc. The vSphere API is just a “view” into the vSphere product. Also very helpful is the Managed Object Browser(MOB) which allows you to explore the inventory and see the managed object internals. Optionally, you can use VIJava Browser.
Once you have a good understanding of vSphere, you should check out the object model of vSphere API. The UML diagram gives you a high level overview on managed objects available in the API. For a complete listing of all the object types, you can check out here and also the API reference.
After that, you have several choices on the language bindings. If you use Java, you want to read this tutorial which helps you to run your first HelloWorld like application in 5 minutes. For others, check out the language binding section.

Where can I download vSphere SDK?
Check out the Web Service SDK at developer community download center.
Note: if you are using the open source VI Java API, go to the http://vijava.sf.net.

Do I need to download vSphere Client? If so, where?
You don’t. But it’s recommended to familiarize yourself with vSphere Client. You can type in this URL in your browser to download it if you haven’t done so: https:/server_ip_or_dns/client/VMware-viclient.exe

What if I don’t have vSphere environment?
You can download the software here and try the evaluation license. The other option is to use SimDK developed by Andrew Kutz.

Where can I find documentations?
All the official documentation of vSphere SDK is here. You can also buy VMware VI and vSphere SDK from Amazon. (Disclosure: it’s written by me.)

Is vSphere API back compatible?
Yes. Check out these articles for more details: vSphere SDK Compatibility, Wire Compatibility of Web Services, What’s Deprecated in vSphere 4.1 API,
Why Some vSphere Java API Methods don’t Work With Old Servers – A Story-of-Compatibility, Tips Working with Older Versions of VMware Infrastructures Using VI Java API 2.0.

Where can I get help?
You can post your questions to the VMware management API forum. For VI Java API related questions, post them to the VI Java API forum. You can also engage consulting service from DoubleCloud Inc.

[Language Bindings]

What language should I use for vSphere API?
The vSphere API is based on SOAP Web Services. As a result, you can use any programming language that supports SOAP. For out of box support, see next question.

What language bindings are available for vSphere API?
Java: vijavaNG, and http://vijava.sf.net
.Net: http://sourceforge.net/projects/vitfordotnet/
Python: https://github.com/vmware/pyvmomi, and https://code.google.com/p/pysphere/
Ruby: https://github.com/rlane/rbvmomi
Perl: http://www.vmware.com/support/developer/viperltoolkit/
PowerShell: http://www.vmware.com/support/developer/PowerCLI/
JavaScript: https://labs.vmware.com/flings/vsphere-sdk-for-javascript

You can use VI Java API with JVM based languages like JRuby (Ruby), Jython (Python), Scala, etc. Check out the vSphere Java API section.Currently there is no PHP support for vSphere API.

[vSphere Java API]

What is VI Java API?
Virtual Infrastructure API is an open source project created by Steve Jin from VMware R&D. It aims to simplify the use of VI SDK and improve the performance. This API is also known as vSphere Java API because of the name change of VI to vSphere.

How is this API different from VI SDK?
This API is built on top of the web services interfaces defined in WSDL included in VI SDK. To use this API 1.0, you have to get VI SDK installed and configured first. For more information on how to install VI SDK, please refer Developer’s Setup Guide.
Since version 2.0, you don’t need any installation and configuration of VI SDK. All you need is two jar files of this API and dom4j, which are all included in the binary download.

What does this API mean to me?
If you are using Java to develop applications talking to VMware Infrastructure (vSphere), this API is for you. Using this API instead of the VI SDK web services interfaces results in significantly less line of code, much faster, and much more readable code.
Here are two samples with the same functionality written with VI SDK (part of 100 lines) and with VI Java API (all 28 lines). You can tell the difference by yourself.
Also, take a look at the testimonials from the community.

What is released?
The binary, source code, and over 50 samples showing how to use the API. There are two different bundles: one with binary only for runtime; the other with all source and samples.

Where should I get started?
First, please check out the Get Started Tutorial. Optionally, read these two short documents: Get started with VI Java API (2 pages), and Object model of VI Java API (3 pages) listed at VI Java API documentation Links to PDF files are included in the documents.
Secondly, go to the download page and download the latest release. Once the downloaded jar file is included in your existing VI SDK project’s classpath, you can start to program your first HelloVM program. Note: With 2.0 and beyond, you don’t need any jar files from VI SDK.

Can I use the API in Jython, Groovy, Scala, Ruby?
You can use the API in any JVM languages like Jython, Groovy, Scala, etc.
Here are tutorials:
How You Can Use VI Java API in Scala: A Quick Sample by Dave Briccetti
Ruby to Manage and Automate VMware vSphere? by Martin Jackson
Easy VMware Development with VI Java API and Groovy by Aaron Sweemer.
Two More Jython Samples Managing VMware vSphere by David Rousseau
Scripting VI Java With Jython by Steve Jin

Does this project relate to other open source virtualization projects?
There is VI Perl project on sourceforge.net. We are always looking for opportunities to collaborate and work with the community to build best in class, open source Java API, and utilities that will improve the overall user experience of VI SDK.

Where can I find Javadoc of the API?
There is unfortunately no Javadoc coming with API. One reason for this is that the API has faithfully followed the object model of vSphere API, and as a result the vSphere API reference can be used. The key differences are: for the every property of managed object, VI Java API has an equivalent getter method; for the every method in vSphere API reference, forget about the first _this parameter and use real types instead of ManagedObjectReference.

The commercial product vijavaNG comes with a full javadoc. For more information, check out here.

Where can I find the sample code and API source code?
Click here for Sample code. Note: before you run the samples, make sure you change the URL/username/password, and possible other parameters in the samples.
For API source code, check here.

What is the license?
BSD.

Is the API supported by VMware?
There is no support of the open source project from VMware, but via community forum. So far, it has worked pretty well. See these testimonials and check out the forum for frequency of Q&As.

Who is using the API?
Many companies like Cisco, HP, NetApp, Brocade, Juniper, etc are using the API. For more, check out the poweredby page. Note that the companies listed there are just small number of partners using the API which has been downloaded for more than 12,000 times as of Feb 2011.

Why Can’t I use Java 1.5?
The new Just Enough Web Service engine uses a new feature in 1.6. The feature can be downloaded Java WS pack to run with 1.5. To achieve that, you need to tweak one line of the VI Java API source code by adding two lines to XmlGen.java

import com.sun.xml.bind.DatatypeConverterImpl; //for 1.5 DatatypeConverter.setDatatypeConverter(DatatypeConverterImpl.theInstance);

BTW, Sun Java 1.5 had reached its end of service life by Nov 3, 2009. You should upgrade to 1.6 anyway.

Can I extend the API?
Yes. Check here.

How can I help with this project?

There are many ways you can help:
. Develop your applications using this API and let us know the bugs and your wish list;
. Help others in the project forum;
. Share your experience with others;
. Become a contributor of this project.

[API Usage]

How to set up proxy with the VI Java API?
It’s no different for other Java applications. Check out details here.

Can I set up connection timeout in VI Java?
Yes, check here.

How can I ignore the SSL certificate? Should I?
It really depends. If you want to ignore the certificate, you can simple provide a “true” value to the ServiceInstance constractor as follows:

ServiceInstance si = new ServiceInstance(new URL(urlStr), username, password, true);

Even you ignore the certificate, the traffics between are still encrypted. But the client won’t authenticate if the server is what it claims to be. I recommend you to ignore the certificate in development time, just for convenience.
If you put false, you have to import the server SSL key into Java keystore and provide the path to the keystore when you run the application.

How can I get an managed object if I have its ID, for example task-id?
Read this article.

How to find a folder for virtual machine or hosts?
The folder itself is a type which can hold datacenters, virtual machines, hosts, etc. It’s determined by its property “childType.” Check this post for in-depth discussion:

How Can I get memory information of a host in vSphere?
Check out this post.

Can I run a command or script in a guest OS with vSphere API?
As of vSphere 4.1, you cannot run a script in a guest OS. To achieve that, you want to take a look at the VIX API.

Why can’t get IP address of a virtual machine via API?
Most likely you don’t have VMware Tools installed in your guest OS. Make sure it’s part of your virtual machine template so that any cloned VMs have it. Check out this article for more details. It’s also possible that your virtual machine is not powered on.

Can I embed a virtual machine console in my Java application?
No. But you can embed it within a browser or VMRC application. Check out this post.

Can I retrieve and change the vmx file of a virtual machine?
Yes. Check out here.

Can I capture screenshot of a virtual machine?
Yes, check out the CreateScreenshot_Task() method defined on VirtualMachine object. More can be found at this post.

Can I export and import OVF with vSphere API?
Yes. More are here and here.

How can I delete a virtual machine?
Check out here.

Can I create my own Task and Event using vSphere API?
Yes. Check here.

How to get Event type?
Check here.

Why isn’t there event type for network port group?
Not everything happened with vSphere has a corresponding event. This post discusses this is in great details.

What performance counters are available?
There are several hundreds of possible counters. Check out this.

Why is real time stat limited within one hour?
Because real time stats are generated every 20 seconds, a big storage space is needed. To save space, a limit is there. To have longer period of stats, you want to increase the stats interval. Check out the fundamentals of vSphere performance management.

Is there an easy to keep update with property changes?
Yes. Check out the caching framework in VI Java API.

[Troubleshooting]

Why can’t I use the API with ESXi via API?
It’s possible that you are using free version of ESXi which doesn’t fully support the API. Check this post, and upgrade your license.

What are the common faults?
Check out here.

What Should I do if I got an exception?
First of all, you need to isolate the exception to see if it’s from vSphere API or a normal programming exception. One simple way is check the full name of the exception. The vSphere API exception normally have package name like com.vmware.vim25.
When it’s a vSphere API exception, check the API reference to see what’s the nature of the exception and what could possibly cause it. With that in mind, check your API parameters and the managed object conditions like power status of a virtual machine. See other FAQs below. You also use server logs and Onyx to help.

Why return com.vmware.vim25.NotSupported when calling cloneVM?
Some method for example cloneVM_Task() is only supported on vCenter. When you call ESX or ESXi, you may get this NotSupported exception. So, switch to vCenter server instead. It’s also possible that you got this with vCenter in some rare cases. The solution is to switch to ESX or ESXi.

Why did I get javax.net.ssl.SSLHandshakeException?
It’s possible that you haven’t correctly set up the certificate with your Java keystore. If you are in development phase, you can temporarily bypass this by ignore the certificate as described in a previous FAQ.

What can I do if I got com.vmware.vim25.InvalidRequest exception?
The InvalidRequest means your parameter to vSphere API is not expected by the server: either missing some required parameters, or giving inappropriate values. It’s mostly hard to find out which parameters. You want to check out the sample code and compare them with yours. If there is no clue, you want to use Oynx to record vSphere Client and compare that of your application.

Why did I get com.vmware.vim25.InvalidProperty exception?
It’s most likely you’ve specified a wrong property name or a wrong property path while using the PropertyCollector managed object. The VI Java API has provider getter methods for all direct properties of all managed objects. You will much less like to get this InvalidProperty exception using VI Java API. Even so it’s still possible to get this exception. Check out this article for in-depth discussion.

Why did I get com.vmware.vim25.TaskInProgress?
The TaskInProgress exception is caused by multiple calls at the same time. If you can limit one call on one VM at a time, the issue may go away. Check the chapter 18 of my book (http://amzn.to/97ZyAg) on multithreading issues in details.

Why I got java.lang.InstantiationError while running VI Java API?
Most likely you use VI Java 2.0 and newer, but still have jar files of Apache AXIS in your classpath. Remove all of them, and you should be able to run.

Why does it fail with some username/password?
You need to escape the special characters like <, >, ‘, “, & in a string passed into the API because VI Java does not escape them for you in 2.0 and 2.1 and thus fails the XML parser on the server side. We may change this in the future.

How to turn on logs of vCenter and ESX?
For ESX, check this article. For vCenter, check out LucD’s blog.

My server application works fine in lab but doesn’t scale in production. Any thought?
It’s possible with session management. Check out this article for tips.

What tools to troubleshoot an application built on vSphere API?
First of all, your application can be debugged as any other applications. You should get familiar with the debuggers of your language and IDE.
Besides the debuggers, you want to look at Onyx. This is essentially a proxy which can intercept the traffics between your application and vCenter/ESX. You can analyze the XML messages and compare them with those recorded between vSphere Client and vCenter/ESX.
If you want to monitor every possible IP packet, you can take a look at WireShark. It may take a little effort to set up the SSL certificate for decrypting the messages, and set up the filters for interested packets.
You can also switch HTTPS to HTTP and use tools like TcpMon to log the HTTP traffic. Because HTTP is not enabled by default, I wouldn’t recommend it when Oynx can serve your need.

Note: your feedbacks and suggestions are important to me. Please feel free to comment here.

  • 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.