vSphere API as a Web Service

The vSphere API is a language-neutral Web service that runs on ESX/ESXi and vCenter Server systems. The vSphere API complies with the Web Services Interoperability Organization (WS-I) Basic Profile 1.0. The WS-I Basic Profile 1.0 includes support for:

■	XML Schema 1.0

■

SOAP 1.1

■

WSDL 1.1

For information about the WS-I Basic Profile 1.0, go to the Web Services Interoperability Organization (WS-I) Web site at http://www.ws-i.org.

Web services support operations, which are the same as methods in other programming languages. The vSphere API Web service provides access to all operations necessary for monitoring and managing vSphere components, such as compute resources, virtual machines, networks, storage, and so on.

WSDL Files and the Client-Side Proxy Interface

The vSphere Web Services SDK provides a set of WSDL (Web Services Description Language) files that define the vSphere Web Services API. Web-services development tools such as JAX-WS wsimport, or Microsoft .NET wsdl.exe use these WSDL files to generate client-side proxy code (stubs).

The client proxy provides a language-specific vSphere API, for example, using Java or C#. The proxy facilitates remote method invocation, organization of object data, and other aspects of distributed, object-oriented, applications programming. Your client application calls proxy interface methods. The client proxy uses SOAP (Simple Object Access Protocol) to exchange WSDL messages with a vSphere server.

Client-Server Communication Through a Client Proxy Interface is a representation of a client application that uses the client proxy interface to call a method. The client proxy interface is based on the WSDL definitions.

Client-Server Communication Through a Client Proxy Interface

To use the VMware client proxy interface, you must import the vSphere API client libraries in to your client application using the following Java and C# statements.

C#	using VimApi;
Java	import com.vmware.vim25.*;

Important The vSphere Web Services SDK includes Java client-side proxy code that was generated using the JAX-WS toolkit. If the versions of Java and JAX-WS on your development platform are the same as those used to generate the proxy interface shipped in the SDK, you do not have to generate client-side proxy code from the WSDL. See the Developer’s Setup Guide for information about configuring a development environment for the vSphere Web Services SDK.

Network Access to the vSphere Web Service

Your client application can use the vSphere API to communicate with vSphere servers over HTTPS (HTTP over an encrypted Secure Sockets Layer connection) at port 443. HTTPS is the default protocol. You can configure the server to support HTTP. Use HTTP access only for test or development environments, not for production. See the Developer’s Setup Guide for details.

Language-Specific Classes and Methods

The SOAP tools generate language-specific classes and methods that match the WSDL definitions. The tools also produce objects and methods that are not in the WSDL files.

■	Generated objects. The additional objects provide access to the vSphere Web Service to establish the client-server connection (VimServiceLocator, AppUtil) and declare the methods defined for the vSphere API (VimPortType, VimService).

■	Generated methods. The additional methods are accessor (getter) and mutator (setter) methods for properties. For Java, the method names are constructed by adding get and set prefixes to a property name, and changing the first character of the property name to upper case.

Client Proxy Definitions identifies client proxy definitions for the vSphere Web Services SDK WSDL.

Client Proxy Definitions 

Element Access	Java	C#
Access to vSphere Web service (HTTPS/HTTP)	VimServiceLocator class	AppUtil class
Access to vSphere API methods	VimPortType class	VimService class
Access to vSphere API properties	getPropertyName and setPropertyName methods defined for data objects	get and set methods defined for properties
vSphere API data objects	Data objects in the vSphere API (see the vSphere API Reference) defined as objects in the proxy interface

The following code fragments show getter and setter method declarations for the AfterStartupTaskScheduler.minute property.

Java

public int getMinute() {

return minute; }

public void setMinute(int minute) {

this.minute = minute; }

C#

public int minute {

set; get; }

You can extrapolate the getter and setter methods that are available in the client proxy interface from the vSphere API Reference. For example, the ScsiLun data object has a displayName property. For the Java API, you can use a setDisplayName method to assign a string value to the property, and obtain the string value by using the getDisplayName method. The vSphere Web Services SDK includes Java and C# sample code that illustrates using the proxy interfaces. See Client Applications.

Mapping XML Data Types to Java and C# Data Types

In this guide, the UML class and object diagrams use the primitive data type names such as string and integer, without the XML Schema definition namespace prefix (xsd:). The vSphere API Reference contains the complete data type name, such as xsd:string. The data types map to the primitive data types of the programming language used for the client application.

Standard XML Schema Primitives to Java and .NET Data Type Mappings lists some of the more common XML primitive data type mappings.

Standard XML Schema Primitives to Java and .NET Data Type Mappings 

XML Schema	Java	.NET Data Type
xsd:base64binary	byte[]	Byte[]
xsd:boolean	boolean	Boolean
xsd:byte	byte	SByte
xsd:dateTime	java.util.Calendar	DateTime
xsd:decimal	java.math.BigDecimal	Decimal
xsd:double	double	Double
xsd:float	float	Single
xsd:int	int	Int32
xsd:string	java.lang.String	String