Product Announcements

Introduction to the vSphere API Part 1

By William Lam, Sr. Technical Marketing Engineer

In our previous article, we quickly looked at the differences between an API and an SDK. In this article, we will take a look at a high level summary of what makes up the vSphere API.


The vSphere API provides an interface for users to access the capabilities and features of the vSphere platform which includes the vCenter Server and ESX(i) hosts. Capabilities such as host management, virtual machine provisioning, monitoring, etc. are exposed as aWeb Services API from both a vCenter Server and ESX(i) host. Depending on the feature, certain functionalities of the API will only be available at the vCenter Server (e.g. VM Cloning or Storage DRS).


The complete vSphere API is documented in thevSphere API Reference guide which is available online and can also be downloaded here.


Access to the vSphere API is governed by the variousvSphere Editions which provides both read and write access to the API. If you are using vSphere Hypervisor (free edition of ESXi), the vSphere API will only be available as read-only.

Object Model

In order to retrieve properties, perform operations or modify entities within the vSphere API, it is important to understand the vSphere Object Model’s structure and relationships. The vSphere API consists of three types of objects: Managed Object which is a server side object, Managed Object Reference which is a client reference to a Managed Object and Data object which contains information about a Managed object.  

Inventory Hierarchy

The vSphere API organizes its entities (Datacenter, HostSystem, VirtualMachine, etc) in an inventory hierarchy. This inventory hierarchy structure is similar for both a vCenter Server and an ESX(i) host, but for a vCenter Server, it can be more complex. Understanding the hierarchy and the object relationships is crucial for navigating and searching through the vSphere API.

Property Collector

The property collector is a very important interface in the vSphere API as it provides a way to monitor and retrieve properties of managed objects in the vSphere inventory. The property collector may seem complex, but it is a very powerful tool once you understand how it works. The functionality of the property collector is abstracted in some of our vSphere SDKs to make it easy to use but is also available directly for advanced users who want to leverage the full capabilities of the property collector.

Permissions, Roles and Privileges

Users must be authorized to perform any type of operation using the vSphere API. This authorization is governed by permissions, roles and privileges which are constructs within the vSphere API.

  • A Permission associates a user or group with a role
  • A Role is assigned to one or more privilege
  • A Privilege defines a basic right (e.g. power on or reset a VM)

An entity in vSphere can have multiple permissions, but only one permission per user or group.

Hopefully this introduction provided you with a good overview of the vSphere API. In the next few articles, we will dive into more details on the vSphere Object Model, Inventory Hierarchy and Property Collector. Stay tuned!

Get notification of new blog postings and more by following lamw on Twitter:  @lamw