vCloud API programming guide for service providers

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.

Revision History

Revision Date

Description

Release Vehicle

Status

25 SEP 2017

API Version 29.0

vCloud Director 9.0

supported

21 FEB 2017

API Version 27.0

vCloud Director 8.20

supported

26 MAY 2016

API Version 20.0

vCloud Director 8.10

supported

N/A

API Version 19.0

vCloud Air Compute Service

deprecated

N/A

API Version 18.0

vCloud Air Compute Service

deprecated

25 JAN 2016

API Version 17.0

vCloud Air Compute Service

supported

N/A

API Version 16.0

vCloud Air Compute Service

deprecated

15 DEC 2015

API Version 14.0

vCloud Air Compute Service

deprecated

21 SEP 2015

API Version 13.0

vCloud Air Compute Service

supported

22 AUG 2015

API Version 12.0

vCloud Air Compute Service

deprecated

10 JUL 2015

API Version 11.0

vCloud Air Compute Service

deprecated

10 SEP 2015

API Version 9.0

vCloud Director 8.0, vCloud Air Compute Service

supported

15 APR 2015

API Version 7.0.

vCloud Air Compute Service

deprecated

16 MAR 2015

API Version 6.0

vCloud Air Compute Service

deprecated

13 JAN 2015

API Version 5.11

vCloud Air Compute Service

deprecated

24 OCT 2014

API Version 5.10

vCloud Air Compute Service

deprecated

19 SEP 2014

API Version 5.9

vCloud Air Compute Service

deprecated

05 SEP 2014

API Version 5.8

vCloud Air Compute Service

deprecated

01 AUG 2014

API Version 5.7.

vCloud Air Compute Service

deprecated

07 OCT 2014

API Version 5.6

vCloud Director 5.6

supported

19 SEP 2013

API Version 5.5

vCloud Director 5.5

supported

10 SEP 2012

API Version 5.1

vCloud Director 5.1

Deprecated. Unsupported after vCloud Director 9.0.

01 SEP 2011

API Version 1.5

vCloud Director 1.5

Deprecated. Unsupported after vCloud Director 9.0.

30 AUG 2010

API Version 1.0

vCloud Director 1.0

not supported

14 APR 2010

API Version 0.9

N/A

not supported

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

1

Logging In

To begin using the API, you request the system to create a Session object. In this request, you supply your credentials in an Authorization header of the form prescribed by the identity provider that your organization uses. The response includes an authorization token, which you must include in subsequent requests.

2

Finding a Catalog and a VDC

Before you can deploy a vApp, you must find a vApp template in one of your organization's catalogs and a VDC in your organization to use for the deployment.

3

Retrieving the Contents of a Catalog

You can make a GET request to a catalog URL to retrieve a list of vApp templates and media images referenced by the catalog.

4

Retrieving a Catalog Item

You can examine the list of items in a catalog to find items of interest based on the values of their name and type attributes. You must retrieve a catalog item to get a Description and a usable reference to the underlying object.

5

Retrieving Deployment Information From the VDC

To deploy your template as a vApp, you must specify an organization VDC to deploy it in and an organization VDC network to connect it to.

6

Deploying the vApp

To create a vApp from a vApp template, you must bind the template's abstract resource requirements, such as network connections, storage resources, memory, and CPU capacity, to appropriate resources in the target VDC. This binding operation is called instantiation.

7

Getting Information About a vApp

When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use this URL with a GET request to retrieve information that you can use to connect to the vApp, modify its configuration, and operate it.

8

Displaying the Virtual Machine Console

After a vApp is powered on, you can retrieve a screen ticket from any of its virtual machines. You use that ticket with the VMware HTML Console SDK to access the virtual machine console from a browser.

9

Undeploying, Powering Off, and Deleting the vApp

After you undeploy a vApp and power it off, you can use an HTTP DELETE request to delete the vApp object.

10

Logging Out

To log out and terminate a vCloud API session, delete the Session you created when you logged in.

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.


State diagram illustrating how an uploaded OVF package becomes a vApp template, and an instantiated template becomes a vApp

<a class=" external" title="Instantiation parameters for a vApp template can modify the virtual hardware configuration, including network connections, of the virtual machines defined in the template." href="https:/
 
 

Have you tried Cloud4U cloud services? Not yet?

Go to the Main Website

Try for free

  • 68 Users Found This Useful
Was this answer helpful?

Related Articles

How to access VMware Cloud Director via the vCloud API

Overview To perform some tasks in a CLOUD4Y environment, you may need to access VMware Cloud...

Changing Advanced Edge settings via API using PowerShell 7

In this article, we will take a look on some Advanced Edge Gateway actions available to the...

Changing EDGE settings with the vCloud API

Getting Started This tutorial shows how to receive, modify and send XML blocks representing the...

vCloud Director API for NSX. Programmers’ Guide

vCloud Director API for NSX The vCloud Director API for NSX is a proxy API that allows vCloud...