Knowledgebase

This version of the vCloud API Programming Guide for Service Providers contains information about version 29.0 of the vCloud API.

VMware provides many different APIs and SDKs for applications and purposes. This guide provides information about the vCloud API for developers interested in building RESTful clients from VMware vCloud Director.

Guide Version History

The version number of the vCloud API is incremented each time one of its types or operations changes. The vCloud API Programming Guide for Service Providers is revised with each release of VMware vCloud Director. Versions of the vCloud API that were not present in the VMware vCloud Director release are described in the Air Compute Service vCloud Programming Guide. An API version might be deprecated if a newer API version supports an equivalent set of features. Use of a deprecated API is not recommended. Support for an API version may be removed in a release after it is deprecated.

Target Audience

This guide is intended for software developers who create VMware Ready cloud services, including the interactive clients of VMware vCloud Director. This guide discusses porting state (REST) and RESTful conventions, the Open Virtualisation Format specification, and VMware virtual machine technology. You should be familiar with these and other common technologies such as XML, HTTP, and the Windows or Linux operating system.

Related Publications

Link to vCloud API Schema Reference contains reference material for all elements, types, requests, and operations in the vCloud API. It also includes schema definition files. A link to the schema is available at https://code.vmware.com.

About the VMware vCloud API

The VMware vCloud API provides support for developers building interactive clients for VMware vCloud Director using the RESTful application development style.

VCloud API clients communicate with servers over HTTP by exchanging representations of vCloud objects. These representations are in the form of XML elements. You use HTTP GET requests to retrieve the current representation of an object, HTTP POST and PUT requests to create or modify an object, and HTTP DELETE to delete an object.

Hello vCloud: A Simplified RESTful Workflow

VCloud API clients and vCloud Director servers communicate over HTTPS, exchanging XML representations of vCloud API objects.

This simplified RESTful workflow example includes requests to discover and deploy a specific vApp, in this case an FTP server connected to the public Internet.

These examples assume that you have access to a directory that contains a specific vApp template and an organisation that supports public Internet connections. The workflow and examples are flexible and can accommodate different vApp templates and cloud capabilities.

Requirements

If you want to run Hello vCloud samples, please make sure that the following conditions are met

■ You have the credentials of a user with the vApp Fixed Author privilege set or an equivalent privilege set.

■ Your organisation has at least one VDC with at least one network. For information on creating VDCs and networks, see Managing an Organisation.

■ Your organisation contains a directory in which at least one vApp template is available. To add a vApp template to the catalogue, see Deploying an Organisation.

Procedure

Exploring the clouds

You can use HTTP GET requests to browse containers such as organisations, directories and VDCs in the cloud.

The responses to these requests contain metadata about the container itself and links to the objects it contains. These links are represented in link elements, which have href attributes that the client can use in requests to get more information about the objects. This process is sometimes called sequential discovery because the content of a single response provides links to the sources where you can look for more information. The hierarchical structure of vCloud API container objects lends itself to a graphical representation as a folder hierarchy or tree view of vCloud API objects, and allows customers to use the same set of objects and operations to implement a breadth or depth-to-view approach.

The list of entry points from which to start browsing is contained in the Session element that is returned in response to a successful login. The content of this list depends on your rights and privileges.

links: 

Create a vCloud API session
Retrieve a List of Organizations Accessible to You

Retrieve an Administrative View of a Cloud
Retrieve a List of vSphere Platform Operations and Objects for a Cloud
XML Representations in the vCloud API

Organisation Initialization

The vCloud API provides several ways to make vApp templates, vApps, media images, and independent volumes available to users in the vCloud Director organisation.

The vCloud API allows you to upload and download OVF packages and ISO media images. Operations are characterised as downloads when content is transferred from the vCloud API client system to the target directory in the vCloud client organisation, and as uploads when the vCloud API client requests a transfer of content from vCloud Director. A POST request initiates a download, and a GET request initiates a upload. The vCloud Director Transfer Service facilitates uploads and downloads and provides temporary storage for files. Downloaded vApp templates and media images become available as directory items in the destination directory.

In addition to uploading, you can use the following operations to provision vApps, vApp templates and media images to the organisation:

Clone

The vCloud API cloneVApp operation creates a copy of a vApp in a specified VDC. You can specify whether to delete the source vApp after the operation completes. Deleting the source vApp after cloning moves or renames it.

Capture

The vCloud API captureVApp operation creates a vApp template from a vApp and places the template in a specified catalogue.

Import

The system administrator can import a virtual machine from vCenter Server that is registered in the cloud. You can import the virtual machine as a vApp or as a vApp template. You can add an imported template to a catalogue or download it as an OVF package.

Accept

By default, the system automatically discovers vCenter VMs contained in any resource pool that supports an organisation's VDC. A system administrator can also configure an Organisation VDC to adopt existing vCenter resource pools and the VMs they contain. The system administrator can make these discovered VMs available for adoption by organisation members.

Subscribe

Organisations with the appropriate permissions can create external subscription catalogs. The content of these catalogs is downloaded from a catalog hosted on another instance of vCloud Director or from any website that implements the VMware Content Subscription Protocol. See Create a Catalog With an External Subscription.

You can also create independent disks that are included in the VDC organisation and can be connected to any virtual machine in that VDC.

Deploying and using vApps and virtual machines

A vApp object contains one or more virtual machines and provides detailed specifications of those virtual machines and the networks to which they are connected. The vCloud API supports programmatic access to various self-service datacenter operations that enable users to create, configure, deploy and manage vApps.

The initial configuration of a vApp and the virtual machines it contains is defined in the OVF package on which its initial template is based. In the vCloud API, vApp templates are based on OVF 1.0. These templates can be extracted from directories and converted into virtual systems called vApps through a process called an instance, which binds the abstract resource requirements of the template to the resources available in the VDC.

After you create a vApp using one of the methods described in the 'About instantiation' section, you can make further changes to its configuration using procedures such as those described in the 'Reconfiguring vApps and virtual machines' section. Any configuration changes you make during creation or reconfiguration are discarded when you delete the vApp, but you can save them by capturing the vApp as a template. See Capturing a vApp as a template.

About OVF

OVF is a widely used standard format for many virtualisation technologies.

• Virtual machines and appliances are distributed by many vendors as OVF packages.
• Many vendors, including VMware, offer tools that simplify the creation and configuration of OVF, support the conversion of virtual machines on existing virtualisation platforms to OVF, or both.
• OVF can express the complex relationships between virtual devices in enterprise applications. Much of the complexity can be handled by the device author rather than the user deploying the device.
• OVF is extensible, so new policies and requirements can be brought into ISVs and deployed by virtualisation platforms that support them without requiring changes to other clients, other platforms, or the vCloud API itself.

Administrators and advanced users should familiarise themselves with the details of the OVF standard before developing applications using the vCloud API. The full OVF white paper is available at http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf 
An OVF white paper is available at http://www.dmtf.org/standards/published_documents/DSP2017_1.0.0.pdf. 

A virtual machine typically consists of one or more virtual disc files that contain the operating system and applications that will run in the virtual machine, and a configuration file that contains metadata that describes how the virtual machine is configured and deployed. The OVF package contains these components plus additional certificate and manifest files. The package can be distributed and stored as a set of individual files or as a single archive file (OVA). The vCloud API does not support uploading or downloading of OVA files.

About DMTF, CIM and RASD
Virtual hardware in OVF package elements is defined using an open standard structure established by the Distributed Management Task Force (DMTF). This structure, called the Common Information Model (CIM), defines virtual hardware resources using the Resource Allocation Setting Data (RASD) schema. In this schema, each virtual hardware class is represented as an item with a specific resource type. Many vCloud API operations that deploy and configure vApps and virtual machines require you to understand and sometimes modify RASD item elements.

You can download the RASD schema files and related information from http://www.dmtf.org/standards/cim/cim_schema_v2191.

The vApp Lifecycle
A vApp contains one or more VM elements, which represent individual virtual machines. It also contains information that defines the operational data for the vApp and the virtual machines it contains. The vApp lifecycle includes several different states:

• An OVF package, the form in which vApps are typically distributed.
• A vApp template, created when a client loads an OVF package into a catalogue.
• Undeployed vApp, created when a vApp template instance is created without deployment, or when a deployed vApp is not deployed.
• A deployed vApp that is ready to be powered on and managed. Instantiation can involve deployment, power-on, or both.