Knowledgebase

This guide covers version 29.0 of the vCloud API, which corresponds to this release of VMware vCloud Director. It is designed for developers building RESTful clients to interact with and extend the capabilities of vCloud Director.

Guide Version History

We revise this guide with each release of VMware vCloud Director. The vCloud API version number increments whenever its types or operations change.

Note: We may deprecate an API version if a newer version supports an equivalent feature set. We strongly recommend against using deprecated APIs, as support for them may be removed in a future release.

Who Should Use This Guide

This guide is for software developers who create VMware Ready cloud services, including interactive clients for vCloud Director. To get the most from this guide, you should be familiar with:

• REST principles and stateless architecture

• The Open Virtualization Format (OVF) specification

• VMware virtual machine technology

• Common web technologies like XML and HTTP

Related Resources

• vCloud API Schema Reference: Find comprehensive reference material for all elements, types, requests, and operations in the vCloud API, including schema definition files. Access the schema at https://code.vmware.com.

Introduction to the VMware vCloud API

The VMware vCloud API enables developers to build interactive clients for VMware vCloud Director using a RESTful style. Clients communicate with servers over HTTP by exchanging XML representations of vCloud objects.

• Use HTTP GET to retrieve an object.

• Use HTTP POST and PUT to create or modify an object.

• Use HTTP DELETE to remove an object.

Hello vCloud: A Simplified RESTful Workflow

This example walks through a basic workflow to discover and deploy a vApp (for instance, an FTP server). The process involves exchanging XML representations of objects over HTTPS.

These examples assume you have access to an organization with a vApp template and a network that supports public Internet connections. The workflow is flexible and can adapt to different templates and cloud capabilities.

Prerequisites

To run the "Hello vCloud" samples, ensure you meet these conditions:

• You have user credentials with the vApp Author privilege set (or equivalent).

• Your organization has at least one Virtual Data Center (VDC) with a network. For details, see Managing an Organisation.

• A catalog in your organization contains at least one vApp template. For details, see Deploying an Organisation.

Procedure

Exploring the Cloud

You can browse cloud containers like organizations, catalogs, and VDCs using HTTP GET requests. The responses contain metadata about the container and link elements with href attributes pointing to the objects it contains.

This process, known as sequential discovery, lets you navigate the API hierarchically. You can start browsing from the entry points listed in the Session element returned after a successful login. The available entries depend on your rights and privileges.

Related links: 

Create a vCloud API session
Retrieve a List of Accessible Organizations

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

Organization Initialization

The vCloud API provides several methods to make vApp templates, vApps, media images, and independent disks available to users.

The vCloud Director Transfer Service manages file transfers, using temporary storage. The API distinguishes between:

• Download: Transferring content from the client system to vCloud Director (initiated with a POST request).

• Upload: Transferring content from vCloud Director to the client (initiated with a GET request).

Downloaded vApp templates and media images become available as catalog items.

Beyond uploads, you can provision resources using these operations:

• Clone: The cloneVApp operation copies a vApp within a VDC. You can optionally delete the source to effectively move or rename it.

• Capture: The captureVApp operation creates a vApp template from an existing vApp and places it in a catalog.

• Import: A system administrator can import a virtual machine from vCenter Server as a vApp or vApp template, adding it to a catalog or downloading it as an OVF package.

• Accept: The system can automatically discover vCenter VMs in resource pools backing a VDC. Administrators can make these VMs available for adoption by organization members.

• Subscribe: Organizations with the right permissions can create catalogs with external subscriptions, pulling content from another vCloud Director instance or any site implementing the VMware Content Subscription Protocol.

You can also create independent disks within a VDC and connect them to any virtual machine in that VDC.

Related links 

Deploying and Using vApps and Virtual Machines

A vApp is a container for one or more virtual machines, specifying their detailed configuration and network connections. The vCloud API provides programmatic access to self-service operations for creating, configuring, deploying, and managing vApps.

The vApp Lifecycle

A vApp progresses through several states:

1. OVF Package: The distribution format for vApps.

2. vApp Template: Created when you upload an OVF package to a catalog.

3. Undeployed vApp: Created when you instantiate a template without deploying it.

4. Deployed vApp: A fully instantiated vApp, ready to be powered on and managed. Instantiation can include deployment, power-on, or both.

The initial configuration of a vApp is defined by its source OVF package. Once you create a vApp, you can reconfigure it. Note that these changes are lost when you delete the vApp, unless you first capture the vApp as a new template.

About OVF

The Open Virtualization Format (OVF) is a key standard:

• It is a widely supported format for distributing virtual appliances.

• Vendor tools simplify OVF creation and conversion from existing VMs.

• It can express complex relationships between virtual devices in enterprise applications.

• Its extensibility allows ISVs to introduce new features without changing the vCloud API.

We recommend that administrators and advanced users familiarize themselves with the OVF standard. You can find the full specification on the DMTF website.

Note: The vCloud API does not support the single-file OVA archive format for upload or download.