Knowledgebase

This release of vCloud API Programming Guide for Service Providers contains information on version 29.0 of vCloud API.

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

History of the guide editions.

The version number of vCloud API is incremented each time any of its types or operations change. vCloud API Programming Guide for Service Providers is revised with each release of VMware vCloud Director. Versions of vCloud API that were not present in VMware vCloud Director release are described in Air Compute Service vCloud Programming Guide. An API version can be deprecated whenever a newer API version supports an equivalent set of features. Using an outdated API is not recommended. API version support may be removed in a release after the deprecation. 

The target audience

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

Related publications

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

About VMware vCloud API

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

VCloud API clients communicate with servers over HTTP by exchanging representations of vCloud objects. These representations take the form of XML elements. You use HTTP GET requests to retrieve 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 that discover and deploy a specific vApp, in this case an FTP server with a connection to the public internet.

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

Precondition

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

■

You have the credentials for a user with the fixed vApp author rights, or equivalent set of rights.

■

Your organization has at least one VDC that has at least one network. For information on creating VDCs and networks, see Managing an Organization.

■

Your organization contains directory where at least one vApp template is available. For information about adding vApp template to the catalog, see Provisioning an Organization.

Procedure

Exploring the clouds

You can use HTTP GET requests to browse containers like organizations, directories and VDCs in the cloud.

The responses to these queries include 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 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 you can start browsing is contained in Session element, which is returned in response to a successful login. The contents of this list are based 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

Related terms:

XML Representations in the vCloud API

Organization initialization

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

The vCloud API allows you to upload and download OVF packages and ISO media images. Operations are characterized as downloads when content is transferred from the vCloud API client system to the target directory in the vCloud client organization and as downloads 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 download. 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 target directory.

In addition to uploading, you can use the following operations to provide the organization with vApps, vApps and media images:

Cloning

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

Capturing

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

Importing

System administrator can import a virtual machine from vCenter server that is registered to the cloud. You can import the virtual machine as vApp or as vApp template. You can add an imported template to a catalog or download it as OVF package.

Adopting

In the default configuration, the system automatically discovers vCenter VMs contained by in any resource pool that backs an organization VDC. A system administrator can also can configure an organization VDC to adopt existing vCenter resource pools and the VMs they contain. The system administrator can make these discovered VMs available for adoption by organization members.

Subscribing 

Organizations that have the appropriate permissions can create catalogs with external subscriptions. These contents of these catalogs are downloaded from a catalog hosted on another instance of vCloud Director, or any Web site that implements the VMware Content Subscription Protocol. See: Create a Catalog With an External Subscription.

You can also create independent disks that are contained in VDC organization and can be connected to any virtual machine in that VDC.

Upload an OVF Package to Create a vApp Template

Download a vApp or vApp Template as OVF

Upload a Media Image

Download a Media Image

Capturing and Importing vApps

Discovering and Adopting vApps

Managing Catalog Items

Creating and Using Independent Disks

View or Change the Owner of an Object

Controlling Access to vApps and Catalogs

Deploying and using vApps and virtual machines

<p class="MsoNormal" st