Product Announcements

Introduction to the vSphere API Part 2: Object Model

By William Lam, Sr. Technical Marketing Engineer

In Part 1 of the series, we provided an overview to the vSphere API. In this article, we will explore the vSphere 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 is a server side object
  • Managed Object Reference is a client reference to a Managed Object
  • Data Object contains information about a Managed Object and can also be used to transfer data between a client and server

Though a Managed Object is the common base type, it can be extended to represent other types of objects and we will see this in an example below.

The vSphere Object Model is complex due to the extensive amount of functionality it provides. To help you visualize the objects and relationships, here is a UML diagram for the vSphere 5 Object Model. The object relationships can be inferred by using the vSphere API Reference. Coloring has been added to highlight some of the important objects, which will be explained later.


Note: The diagram was modified from Steve Jin’s original post here and updated to reflect the vSphere 5 API. This was a great idea by Steve to create visualization for the vSphere API Object Model.

Managed Object

A vCenter Server or an ESX(i) host is composed of many different components such as configurations (objects highlighted in green are configuration related to an ESX(i) host), administrative/management services (objects highlighted in blue) or entities in its inventory (highlighted in orange are entities such as a cluster or virtual machine) to just name a few. These components are generically refereed to as a Managed Object and reside on the server itself. Each Managed Object has a defined type to distinguish them from one another and has an associated set of properties and operations. This provides the information needed to interact with one of these objects whether that is presented through the vSphere Client UI or using one of the vSphere SDKs.

Let’s take a look at an example of a Managed Object, a Datastore:

If we look at the vSphere API reference for a vSphere Datastore, we will see it has some properties defined on the object such as summary which provides a summary information about the datastore or host which provides a reference to all ESX(i) hosts that is attached to this datastore. There are also a set of operations associated with a datastore such as DatastoreEnterMaintenanceMode which is one of the new features in vSphere 5 that allows a user to enter a datastore into maintenance mode.

We can see from the diagram that a Datastore is also a Managed Entity type which in turn is a ExtensibleManagedObject and finally a Managed Object (highlighted in yellow). This concept is a known as as inheritance in OOP (Object Oriented Programming) as a way to share/re-use code for similar objects. Another example of this is the new StoragePod object in vSphere 5, also known as a Datastore Cluster in the vSphere Client UI. From the diagram above, we can see it extends the Folder object and as documented in the vSphere API, it has it’s own unique properties and operations. The StoragePod also inherits from it’s parent object’s attributes as a way to re-use similar properties that are applicable.

The objects that extend the Managed Entity (highlighted in orange) are the most important Managed Objects to the vSphere inventory as well as the ServiceInstance which is an entry point to a vCenter Server or ESX(i) host (highlighted in red). We will dive into these topics further in the next article.

Managed Object Reference

To interact or modify an entity such as a virtual machine or ESX(i) host, a client application like the vSphere Client or one of the vSphere SDK’s needs to be able to reference a Managed Object from the server side, as you can not access the server side objects directly. This reference encapsulates the properties and operations of the Managed Object and it makes available to the client application. This reference is always guaranteed to be unique and persistent for the lifetime of the object within vSphere.

Data Object

As you perform an operation or modifications to a Managed Object, you are transferring data between the client application which can be the vSphere Client UI or one of the vSphere SDK’s. This data that contains properties and operations of a Managed Object is called a Data Object. The data types for the property of a Data Object can be another Managed Object, a simple string, an integer or an enumeration (enum). An enumeration is just a predefined set of values such as the state of a virtual machine will always be poweredOn,poweredOff, or suspend. A Managed Object Reference is also special type of Data Object that represents a Managed Object residing on server side.

Here is a diagram of of a client application interacting with either a vSphere vCenter Server or an ESX(i) host. We can see the client has a Managed Object Reference of a virtual machine and it uses Data Objects as a way to transfer the state changes between the client and server.


Though the vSphere Object Model is complex in nature, hopefully after this you will have a better understanding of how they are represented and how to access their properties and operations within vSphere. In the next article, we will take a look at the vSphere Inventory Hierarchy and how these Managed Objects are organized.


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