VMware vCloud Director - 5.5 Programming Guide

vCloud API Programming Guide

vCloud Director 5.5

This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.

EN-001031-00

vCloud API Programming Guide

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

docfeedback@vmware.com

Copyright © 2009–2013 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at

http://www.vmware.com/go/patents.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

VMware, Inc.

3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

2 VMware, Inc.

vCloud API Programming Guide 7

About the VMware vCloud API 9

Object Taxonomy 10

Objects, References, and Representations 12

Links and Link Relations 12

Client Workflow Overview 17

Using the vCloud API with vCloud Director 21

About the vCloud API Examples 22

Hello vCloud: A Simplified RESTful Workflow 23

Logging In 24

Find a Catalog and a VDC 26

Retrieve the Contents of a Catalog 27

Retrieve a Catalog Item 28

Retrieve Deployment Information From the VDC 30

Deploy the vApp 31

Get Information About a vApp 34

Displaying the Virtual Machine Console 37

Undeploy, Power Off, and Delete the vApp 38

Log Out 40

Exploring a Cloud 41

Summary of vCloud API Browsing Requests 41

Retrieve the Login URL and List of Supported API Versions 43

Create a Login Session Using the Integrated Identity Provider 44

Retrieve a List of Organizations Accessible to You 49

Retrieve an Administrative View of a Cloud 50

Retrieve a List of vSphere Platform Operations and Objects for a Cloud 52

VMware, Inc.

Provisioning an Organization 55

Summary of vCloud API Provisioning Requests 56

Upload an OVF Package to Create a vApp Template 58

Download a vApp or vApp Template as OVF 68

Upload a Media Image 72

Download a Media Image 74

Capturing and Importing vApps 75

Managing Catalog Items 76

Creating and Using Independent Disks 80

View or Change the Owner of an Object 83

Controlling Access to vApps and Catalogs 84

vCloud API Programming Guide

Deploying and Operating vApps 89

Summary of vCloud API vApp and Virtual Machine Operations Requests 91

Create a vApp From a Template 93

Create a vApp From an OVF Package 97

Compose a vApp From Existing Virtual Machines 101

Recompose a vApp to Add or Remove Virtual Machines 103

Clone a vApp 106

Capture a vApp as a Template 108

Update vApp Access Controls 110

Provide User Input Requested by a Virtual Machine 111

Attach or Detach an Independent Disk 112

Creating and Using vApp Snapshots 114

Operate a vApp 115

Configuring vApps and Virtual Machines 116

Creating and Managing Organizations 149

Summary of Administrative Requests 149

Administrator Credentials and Privileges 152

Organization Administration 153

VDC Administration 160

Network Administration 169

Catalog Administration 197

User and Group Administration 219

Working With Roles and Rights 227

Managing and Monitoring a Cloud 235

Summary of System Administration Requests 235

Retrieve or Update System Settings 239

Attach a vCenter Server 240

Finding Available vCenter Resources 242

Create a Provider VDC 251

Create an External Network 261

Create a Network Pool 264

Import a Virtual Machine from vCenter 270

Relocate a Virtual Machine to a Different Datastore 273

Truststore and Keytab Maintenance 275

Retrieve the vSphere URL of an Object 277

Working With Object Metadata 281

Retrieve or Update a Metadata Element 283

Retrieve or Update a Metadata Value 286

Using the Query Service 289

Typed Queries 290

Packaged Queries 294

Query Parameters 299

Add a Metadata Filter to a Query 303

4 VMware, Inc.

Contents

Configuring and Using Blocking Tasks and Notifications 307

Configure Notifications and AMQP Settings 308

Retrieve or Update Blocking Task Settings 318

Monitor Blocking Tasks 324

Take Action on a Blocking Task 325

Extend The Timeout Expiration of an Active Task 327

vCloud Director Extension Services 329

Summary of vCloud API Extension Services Framework Requests 330

Adding or Removing Service Links 336

Service-Specific Tasks and Events 339

Authorization Framework for Extension Service Operations 342

Localization Framework for Extension Services 350

REST APIs for Extension Services 353

XML Representations in the vCloud API 357

XML Namespace Identifiers 359

Common vCloud API Attributes 360

Retrieve an Object as an Entity 362

Index 365

VMware, Inc. 5

vCloud API Programming Guide

6 VMware, Inc.

vCloud API Programming Guide

This edition of the vCloud API Programming Guide provides information about version 5.5 of the vCloud API.

VMware provides many different APIs and SDKs for applications and goals. This guide provides information about the vCloud API for developers who are interested in creating RESTful clients of VMware vCloud Director.

Revision History

The vCloud API Programming Guide is revised with each release of the product or when necessary. A revised version can contain minor or major changes.

Table 1. Revision History

Revision Date Description

19SEP13 API Version 5.5

10SEP12 API Version 5.1

01SEP11 API Version 1.5

30AUG10 API Version 1.0

14APR10 API Version 0.9

Intended Audience

This guide is intended for software developers who are building VMware Ready Cloud Services, including interactive clients of VMware vCloud Director. This guide discusses Representational State Transfer (REST) and RESTful programming conventions, the Open Virtualization Format Specification, and VMware Virtual machine technology. You must be familiar with these and other widely deployed technologies such as XML, HTTP, and the Windows or Linux operating system.

Related Publications

The vCloud API Schema Reference includes reference material for all elements, types, queries, and operations in the vCloud API. It also includes the schema definition files. The schema reference is available in HTML format in the vCloud Director documentation center.

The VMware vCloud Director Administrator's Guide and VMware vCloud Director User’s Guide contain detailed information about many of the objects and operations referred to in this guide. Most users of the vCloud API will find the information in those documents valuable when developing client applications. To access the current versions of these and other VMware publications, go to http://www.vmware.com/support/pubs.

VMware, Inc.

vCloud API Programming Guide

8 VMware, Inc.

About the VMware vCloud API 1

The VMware vCloud API provides support for developers who are building interactive clients of VMware vCloud Director using a RESTful application development style.

vCloud API clients and vCloud Director servers communicate over HTTP, exchanging representations of vCloud objects. These representations take 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 requests to delete an object.

This chapter includes the following topics:

“Object Taxonomy,” on page 10

“Objects, References, and Representations,” on page 12

“Links and Link Relations,” on page 12

“Client Workflow Overview,” on page 17

“Using the vCloud API with vCloud Director,” on page 21

“About the vCloud API Examples,” on page 22

VMware, Inc.

Catalog 2

Catalogitem

em em em

Catalog 1

Catalog 3

vDC2

Catalogitem Catalogitem Catalogitem Catalogitem

users

Media

vApp

template

Media

vApp

TasksList

Organization

vDC1

Media

vApp

template

Media

vApp

Catalogitem

em em em

groups

Network

Publish

External catalog

vCloud API Programming Guide

Object Taxonomy

The vCloud API defines a set of objects common to cloud computing environments. An understanding of these objects, their properties, and their relationships is essential to using the vCloud API.

Figure 1‑1. vCloud API Object Taxonomy

vCloud API objects have the following high-level properties:

Organizations

A cloud can contain one or more organizations. Each organization is a unit of administration for a collection of users, groups, and computing resources. Users authenticate at the organization level, supplying credentials established when the user was created or imported. User credentials are authenticated by the organization's identity provider, which can be either the integrated identity provider included in vCloud Director or an external SAML-based identity provider.

Users and Groups

An organization can contain an arbitrary number of users and groups. Users can be created by the organization administrator or imported from an LDAP directory service or SAML-based identity provider. Groups must be imported. Permissions within an organization are controlled through the assignment of rights and roles to users and groups.

Catalogs

Catalogs contain references to vApp templates and media images. You can configure a catalog in several different ways:

as a repository for local content that can remain private to the catalog owner or can be shared with other users, groups, or organizations in your cloud

as a source of published content, to which other clouds can subscribe.

10 VMware, Inc.

Chapter 1 About the VMware vCloud API

as a local repository for content published by another cloud or any Web

site that hosts a VMware Content Subscription Protocol (VCSP) endpoint.

An organization administrator or catalog owner controls catalog sharing. Organization administrators in organizations that have permission to publish catalogs control publication and subscription options for catalogs in their organization. A system administrator can enable background synchronization of catalogs with external sources and set background synchronization schedules to regulate consumption of network bandwidth by this activity.

Organization VDCs

Organization VDC Networks

Virtual Systems and Media Images

An organization virtual datacenter (organization VDC) is a deployment environment for virtual systems owned by the containing organization, and an allocation mechanism for resources such as networks, storage, CPU, and memory. In an organization VDC, computing resources are fully virtualized, and can be allocated based on demand, service level requirements, or a combination of the two.

An organization VDC can be provisioned with one or more networks. These organization VDC networks can be configured to provide direct or routed connections to external networks, or can be isolated from external networks and other organization VDC networks. Routed connections require an Edge Gateway and network pool in the VDC. The Edge Gateway provides firewall, network address translation, static routing, VPN, and load balancing services.

Virtual systems and ISO-format media images are stored in a catalog and represented as catalog item objects. Virtual systems are stored as templates, using an open standard format (OVF 1.0). These templates can be retrieved from catalogs and transformed into virtual systems, called vApps, through a process called instantiation, which binds a template’s abstract resource requirements to resources available in a VDC. A vApp contains one or more individual virtual machines (Vm elements), along with parameters that define operational details, including:

How the contained virtual machines are connected to each other and to

external networks.

The order in which individual virtual machines are powered on or off.

End-user license agreement terms for each virtual machine.

Deployment lease terms, typically inherited from the containing

organization, that constrain the consumption of VDC resources by the vApp.

Access control information specifying which users and groups can

perform operations such as deploy, power on, modify, and suspend on the vApp and the virtual machines that it contains.

Tasks

Asynchronous operations are tracked by task objects. Running and recently completed tasks initiated by members of an organization are kept on the organization’s tasks list.

VMware, Inc. 11

vCloud API Programming Guide

Objects, References, and Representations

The vCloud API represents objects as XML documents in which object properties are encoded as elements and attributes with typed values and an explicit object hierarchy defined by an XML schema.

XML representations of first-class vCloud API objects, such as the objects in Figure 1-1, include these attributes.

The object identifier, expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused. The id attribute value is intended to provide a context-free identifier that can be used with the vCloud API entityResolver (see “Retrieve an

Object as an Entity,” on page 362).

type

href

The object type, specified as a MIME content type.

An object reference, expressed in URL format. Because this URL includes the object identifier portion of the id attribute value, it uniquely identifies the object, persists for the life of the object, and is never reused. The value of the

href attribute is a reference to a view of the object, and can be used to access

a representation of the object that is valid in a particular context. Although URLs have a well-known syntax and a well-understood interpretation, a client should treat each href as an opaque string. The rules that govern how the server constructs href strings might change in future releases.

Example: Object id, type, and href Attributes

This XML fragment, extracted from the representation of a vApp, shows its id, type, and href attributes.

Links and Link Relations

The vCloud API makes extensive use of Link elements to provide references to objects and the actions that they support. These elements are the primary mechanism by which a server tells a client how to access and operate on an object.

The server creates Link elements in a response body. They are read-only at the client. If a request body includes a Link element, the server ignores it.

Attributes of a Link Element

In the XML representation of a vCloud object, each Link element has the following form:

12 VMware, Inc.

Attribute values in a Link element supply the following information:

Chapter 1 About the VMware vCloud API

rel

Defines the relationship of the link to the object that contains it. A relationship can be the name of an operation on the object, a reference to a contained or containing object, or a reference to an alternate representation of the object. The relationship value implies the HTTP verb to use when you use the link's href value as a request URL.

type

The object type, specified as a MIME content type, of the object that the link references. This attribute is present only for links to objects. It is not present for links to actions.

href

href attribute is a reference to a view of the object, and can be used to access

name

The name of the referenced object, taken from the value of that object's name attribute. Action links do not include a name attribute.

Table 1‑1. Link Relationships and HTTP Request Types

rel Attribute Value Action or Relationship Description Implied HTTP Verb

abort Abort this blocking task. POST

add Add an item to this container. POST

alternate References an alternate representation of this object. GET

answer Provide user input requested by a virtual machine. POST

authorization:check Check whether an extension service operation is

authorized for an entity.

blockingTask A list of pending blocking task requests in this cloud. GET

bundle:upload Upload an extension service localization bundle. PUT

bundles:cleanup Remove unused extension service localization bundles. POST

catalogItem References the CatalogItem object that refers to this

object.

certificate:reset Removes the SSL certificate used by this service. POST

certificate:update Updates the SSL certificate used by this service. POST

checkCompliance Check that this virtual machine is using a storage profile

of the intended type.

consolidate Consolidate this virtual machine. POST

controlAccess Apply access controls to this object. POST

copy Reserved N/A

deploy Deploy this vApp. POST

disable Disable this object. POST

discardState Discard the suspended state of this virtual machine. POST

disk:attach Attach an independent disk to this virtual machine. POST

disk:detach Detach an independent disk from this virtual machine. POST

POST

GET

POST

VMware, Inc. 13

vCloud API Programming Guide

Table 1‑1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Action or Relationship Description Implied HTTP Verb

down References an object contained by this object. GET

down:aclRules Retrieve the ACL rules for this resource class action. GET

down:apidefinitions Retrieve the API definitions for this extension service. GET

down:apiDefinitions Retrieve the API definitions for this extension service. GET

down:apiFilters Retrieve the API filters for this extension service. GET

down:extensibility Add an extension service to the system. POST

down:fileDescriptors Retrieve file descriptors for extension services APIs GET

down:files Retrieve files for extension services APIs GET

down:resourceClassActions Retrieve the actions defined for this extension service

down:resourceClasses Retrieve the resource classes defined by this extension

down:serviceLinks Retrieve the service links defined by this extension

down:serviceResources Retrieve the list of extension service resources of this

down:services Retrieve the list of registered extension services. GET

download:alternate Reserved N/A

download:default References the default location from which this file can

download:identity References the extended OVF descriptor of this vApp

edgeGateway:configureServices Update the network services offered by this Edge

edgeGateway:reapplyServices Reapply (after an update) the network services offered

edgeGateway:redeploy Redeploy the vShield Edge supporting this Edge

edgeGateway:syncSyslogSettings Synchronize syslog server addresses used by this Edge

edgeGateway:upgrade Upgrade the backing configuration of this Edge Gateway

edgeGateways List the Edge Gateway objects in this organization VDC. GET

edit Modify this object, typically by replacing its current

enable Enable this object. POST

enterMaintenanceMode Put this virtual machine into maintenance mode. POST

entity Retrieve a representation of the object on which an

entityResolver Retrieve an object id as a context-free Entity element. GET

event:create Create an event in an this organization's event stream. POST

exitMaintenanceMode Take this virtual machine out of maintenance mode. POST

GET

resource class.

GET

service.

GET

service.

class.

GET

be downloaded.

GET template. The extended OVF descriptor contains additional information such as MAC address, BIOS UUID, and NetworkConfigSection

PUT Gateway.

POST by this Edge Gateway.

POST Gateway.

POST Gateway with system defaults.

POST from compact to full.

PUT representation with the one in the request body.

GET operation triggered this notification.

14 VMware, Inc.

Chapter 1 About the VMware vCloud API

Table 1‑1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Action or Relationship Description Implied HTTP Verb

fail Fail this blocking task. POST

firstPage Reference to the first page of a paginated response. GET

installVmwareTools Install VMware Tools on this virtual machine. POST

keystore:reset Removes the keystore used by this service. POST

keystore:update Updates the keystore used by this service. POST

keytab:reset Removes the keytab used by this service. POST

keytab:update Updates the keytab used by this service. POST

lastPage Reference to the last page of a paginated response. GET

media:ejectMedia Eject virtual media from a virtual device. POST

media:insertMedia Insert virtual media into a virtual device. POST

merge Merge one or more Provider VDCs with this Provider

VDC.

migrateVms Migrate virtual machines from this resource pool to a

different one.

move Reserved N/A

nextPage Reference to the next page of a paginated response. GET

orgVdcNetworks List the organization VDC networks supported by this

Edge Gateway.

ova Reserved N/A

ovf References the OVF descriptor of this vApp template. GET

power:powerOff Power off this vApp or virtual machine. POST

power:powerOn Power on this vApp or virtual machine. POST

power:reboot Reboot this vApp or virtual machine. POST

power:reset Reset this vApp or virtual machine. POST

power:shutdown Shut down this vApp or virtual machine. POST

power:suspend Suspend this vApp or virtual machine. POST

previousPage Reference to the previous page of a paginated response. GET

publish Share this catalog. POST

publishToExternalOrganizations Publish this catalog externally POST

recompose Recompose this vApp to add, remove, or reconfigure

virtual machines.

reconfigureVm Update multiple sections of a virtual machine. POST

reconnect Reconnect this vCenter Server to the system. POST

refreshStorageProfiles Refresh the list of storage profiles that exist on the

vCenter service backing this Provider VDC.

refreshVirtualCenter Refresh the representation of this vCenter server POST

relocate Relocate this virtual machine. POST

remove Remove this object. DELETE

remove:force Force removal of this object. DELETE

POST

GET

POST

VMware, Inc. 15

vCloud API Programming Guide

Table 1‑1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Action or Relationship Description Implied HTTP Verb

repair Repair this host or network. POST

resourcePoolVmList List the virtual machines using this resource pool. GET

resume Resume this blocking task. POST

rights List the service-specific rights created by this extension

rights:cleanup Remove service-specific rights no longer used by any

screen:acquireTicket Retrieve a screen ticket for this virtual machine. GET

screen:thumbnail Retrieve a thumbnail view of the screen of this virtual

shadowVms List shadow virtual machines associated with the virtual

snapshot:create Create a snapshot of the virtual machines in this vApp. POST

snapshot:removeAll Remove all snapshots created for the virtual machines in

snapshot:revertToCurrent Revert all virtual machines in this vApp to their current

storageProfile References the storage profile for this object. GET

subscribeToExternalCatalog Add an external subscription to this catalog. POST

sync Synchronize this catalog or catalog item with its external

syncSyslogSettings Synchronize syslog server addresses used by this vApp

task Retrieve the blocking task that triggered this notification. GET

task:cancel Cancel this task. POST

task:create Create a task object. POST

task:owner Reference to the owner of a task. GET

truststore:reset Remove the truststore used by this service. POST

truststore:update Update the truststore used by this service. PUT

undeploy Undeploy this vApp. POST

unlock Unlock this user account. POST

unregister Unregister this vCenter Server. POST

up References an object that contains this object. GET

update:resourcePools Update the resource pools of this Provider VDC POST

updateProgress Request an update of this task's progress. POST

upgrade Upgrade this host. POST

upload:alternate Reserved N/A

upload:default References the default location to which this object can

vSphereWebClientUrl A URL that you can use to view this object with the

GET service.

POST extension service.

GET machine.

GET machines in this vApp template.

POST this vApp.

POST snapshot.

POST source.

POST network with system defaults.

PUT be uploaded.

GET vSphere Web Client

16 VMware, Inc.

Client Workflow Overview

vCloud API clients implement a RESTful workflow, making HTTP requests to the server and retrieving the information they need from the server’s responses.

About RESTful Workflows

REST, an acronym for Representational State Transfer, describes an architectural style characteristic of programs that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects between a client and a server. In the vCloud API, these representations are XML documents.

In a RESTful workflow, representations of objects are passed back and forth between a client and a server with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response. The URLs at which these documents are available often persist beyond the lifetime of the request or response that includes them. The other content of the documents is nominally valid until the expiration date noted in the HTTP Expires header.

vCloud REST API Workflows

Application programs written to a REST API use HTTP requests that are often executed by a script or other higher-level language to make remote procedure calls that create, retrieve, update, or delete objects that the API defines. In the vCloud REST API, these objects are defined by a collection of XML schemas. The operations themselves are HTTP requests, and so are generic to all HTTP clients.

Chapter 1 About the VMware vCloud API

To write a RESTful client application, you must understand only the HTTP protocol and the semantics of XML, the transfer format that the vCloud API uses. To use the vCloud API effectively in such a client, you need to know only a few things:

The set of objects that the API supports, and what they represent; for example, what is a VDC and how

does it relate to an organization or catalog?

How the API represents these objects; for example, what does the XML schema for an Org look like?

What do the individual elements and attributes represent?

How a client refers to an object on which it wants to operate; for example, where are the links to objects

in a VDC? How does a client obtain and use them?

You can find that information in this Guide, and in the vCloud API Schema Reference. See “About the Schema

Reference,” on page 22.

RESTful Workflow Patterns

All RESTful workflows follow a common pattern.

1 Make an HTTP request, typically GET, PUT, POST, or DELETE. The target of this request is either a

well-known URL such as the vCloud API versions URL, or a URL obtained from the response to a previous request. For example, a GET request to an organization URL returns links to catalog and VDC objects that the organization contains.

2 Examine the response, which always includes an HTTP response code and usually includes a body. In

the vCloud API, a response body is an XML document that can contain any of the following items.

XML elements and attributes that represent object properties

Link elements that implement operations on the object or its contents

Iif the object is being created or modified, an embedded Task object that tracks the progress of the

creation or modification

These operations can repeat, in this order, for as long as necessary.

VMware, Inc. 17

vCloud API Programming Guide

vCloud API REST Requests

To retrieve object representations, clients make HTTP requests to object references. The server supplies these references as href attribute values in responses to GET requests.

Every cloud has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions document, which lists each version of the of vCloud API that the server supports. For each version, the response lists the names and MIME types of the complex types defined in the version's XML namespace, and the version login URL. A system administrator can use that URL to authenticate to the cloud by logging in to the System organization. An authenticated user can discover other vCloud API URLs by making GET requests to URLs retrieved from the login response, and the URLs contained in responses to those requests. See Chapter 3, “Exploring a Cloud,” on page 41.

Requests are typically categorized in terms of the type of requested operation: create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD. Each type of request is characterized by the use of specific HTTP verb to access a URL found in a Link element that has an operation-specific value for its rel (relation) attribute.

Table 1‑2. CRUD Operations Summary

Operation Type HTTP Verb Link Relation Operation Summary

Create POST add Creates a new object.

Retrieve GET down Retrieves the representation of an existing object in its current

Update PUT edit Modifies an existing object.

Delete DELETE remove Deletes an existing object. If the object is a container, you must

state.

remove all of its contents before you can delete it.

For example, this Link element indicates that you can use the URL https://vcloud.example.com/api/admin/org/26 to update the Org object that contains it.

The implied HTTP verb is PUT.

Authentication

HTTP communications between a vCloud API client and server are secured with SSL. The vCloud API also implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to authenticate individual HTTP requests by including an authentication header in the request. See “Logging In,” on page 24.

Request Headers

The following HTTP headers are typically included in vCloud API requests:

All requests must include an HTTP Accept header that designates the vCloud API version that the client supports. The following header indicates that the request is from a vCloud API version 5.5 client:

Accept: application/*+xml;version=5.5

18 VMware, Inc.

Chapter 1 About the VMware vCloud API

Valid values for the HTTP Accept header in this release are:

Accept-Encoding

Authorization

version=5.5

version=5.1

version=1.5

The request is from a vCloud API version 5.5 client.

The request is from a vCloud API version 5.1 client.

The request is from a vCloud API version 1.5 client.

In general, client requests can access objects defined by any version of the vCloud API that is less than or equal to the version specified in the Accept header. Exceptions to this rule are mentioned in the vCloud Director Release Notes.

By default, vCloud Director returns response content as uncompressed XML. Compressing the response can improve performance, especially when the response is large and network bandwidth is a factor. (Requests cannot be compressed.) To request a response to be returned as compressed XML, include the following header:

Accept-Encoding: gzip

The response is encoded using gzip encoding as described in RFC 1952, and includes the following header:

Content-Encoding: gzip

In the default configuration, responses smaller than 64KB are never compressed.

All requests from authenticated clients must include an Authorization header. See “Logging In,” on page 24 for details about the value of this header.

Content-Type

Requests that include a body must include an appropriate HTTP Content-

Type header. Content types for all elements are listed in the schema reference.

In addition, the type attribute of a response body indicates the content type of the document. For example, this response fragment indicates that the content type associated with a CatalogItem object is

application/vnd.vmware.vcloud.catalogItem+xml.

A POST or PUT request that supplies a CatalogItem in the request body requires the following Content-Type header:

Content-Type: application/vnd.vmware.vcloud.catalogItem+xml

When it appears as the value of a Content-Type header or the type attribute of an element in the vCloud API, this string is case-insensitive in requests, and can be returned in either mixed case or lowercase characters in responses.

Request Bodies

vCloud Director uses a validating XML parser that requires elements in a request body to agree with the schema in order and number. Request bodies are rejected as invalid unless they meet the following criteria:

XML namespace attributes must be supplied for all namespaces represented by elements in the request.

See “XML Namespace Identifiers,” on page 359.

VMware, Inc. 19

vCloud API Programming Guide

If multiple namespaces are represented in the request, XML namespace attributes must include an

identifying prefix, and that prefix must be used with all elements from that namespace.

All required elements must appear in request bodies. All elements that appear in request bodies must

appear in the order that the schema establishes, and with content that conforms to the type constraint that the schema specifies.

Request Limits

To guard against denial-of-service attacks, vCloud Director imposes the following limits on vCloud API requests:

Requests cannot exceed 512 KB.

Requests cannot contain more than 4096 XML elements.

Requests cannot have a depth greater than 100.

vCloud API REST Responses

All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty.

Response Content

Response content depends on the requested operation. The response to a GET request is typically the complete representation of an existing object. The response to a PUT or POST request always contains values for the href, name, and id attributes of the object being created or updated. It also contains at most one Task element that you can retrieve to track the progress of the operation. When the Task completes with a status of success, a GET request to the object's href returns all properties of the object. If the Task completion status is not success, the object is in an indeterminate state, and should be deleted.

HTTP Response Codes

A vCloud API client can expect a subset of HTTP status codes in a response.

Table 1‑3. HTTP Status Codes that the vCloud API Returns

Status Code Status Description

200 OK The request is valid and was completed. The response

includes a document body.

201 Created The request is valid. The requested object was created and

can be found at the URL specified in the Location header.

202 Accepted The request is valid and a task was created to handle it.

This response is usually accompanied by a Task element.

204 No Content The request is valid and was completed. The response does

not include a body.

400 Bad Request The request body is malformed, incomplete, or otherwise

invalid.

401 Unauthorized An authorization header was expected but not found.

403 Forbidden The requesting user is not authenticated or does not have

adequate privileges to access one or more objects specified in the request.

404 Not Found One or more objects specified in the request could not be

found in the specified container.

405 Method Not Allowed The HTTP method specified in the request is not supported

for this object.

20 VMware, Inc.

Table 1‑3. HTTP Status Codes that the vCloud API Returns (Continued)

Status Code Status Description

406 Not Acceptable The resource identified by the request is not capable of

generating a response of the type specified in the request's Accept header.

409 Conflict The object state is not compatible with the requested

operation.

415 Unsupported Media Type The resource identified by the request does not support a

request of the specified Content-Type and HTTP method.

500 Internal Server Error The request was received but could not be completed

because of an internal error at the server.

504 Gateway Timeout The server, while acting as a gateway or proxy, did not

receive a timely response from the upstream server specified by the request URL.

Using the vCloud API with vCloud Director

VMware vCloud Director 5.5 supports version 5.5 of the vCloud API. You can use a browser or other HTTP client program to send requests and receive responses.

Chapter 1 About the VMware vCloud API

The vCloud Director REST API Reference documentation includes HTML reference material for all XML elements and complex types defined by the vCloud API. It also includes example XML representations. See

“About the Schema Reference,” on page 22. For information about HTTP client programs to use with

vCloud Director, see “REST Client Programs,” on page 21.

Procedure

1 Configure the vCloud Director REST API base URL.

a Log in to the vCloud Director Web Console as a system administrator.

b In the vCloud Director Web Console, open System Settings > Public Addresses

c Type the URL in the VCD public REST API base URL text box.

2 (Optional) If you want to use the vSphere Web Client to access vCloud API objects on a vSphere server,

verify that the vSphere Web Client URL is enabled for all vCenter servers from which you want to retrieve the vSphere URL of an object.

You can manage this feature on the General tab of the vSphere Properties page of the vCloud Director Web console.

What to do next

Decide on an HTTP client program to use. See “REST Client Programs,” on page 21.

REST Client Programs

Any client application that can send HTTPS requests can be an appropriate tool for developing RESTful applications with the vCloud API.

REST client plug-ins are available for most browsers and many IDEs. The examples in this information were developed using two open-source programs: cURL (http://curl.haxx.se/) and the RESTclient (http://code.google.com/p/rest-client/).

VMware provides additional SDK products that implement language-specific bindings for the vCloud API, and include their own HTTP client capability. See

http://communities.vmware.com/community/developer/forums.

VMware, Inc. 21

vCloud API Programming Guide

About the Schema Reference

The vCloud API Schema Reference includes reference material for all elements, types, queries, and operations in the vCloud API. It also includes the schema definition files.

The schema reference is available in HTML format in the vCloud Director documentation center.

About the vCloud API Examples

The vCloud API Programming Guide includes many examples of HTTP requests and responses. These examples show the workflow and content associated with operations such as browsing, provisioning, and managing your cloud and its contents, and operating virtual systems.

Example requests generally conform to the rules listed in “Request Bodies,” on page 19. Most example responses show only those elements and attributes that are relevant to the operation being discussed. Ellipses (…) indicate omitted content within response bodies. Several additional conventions apply.

The following HTTP header, which is required in all requests that access version 5.5 of the vCloud API,

is omitted from most examples.

Accept: application/*+xml;version=5.5

All other request headers required by the vCloud API are included in example requests that are not

fragments of some larger example. Although the examples show these strings using the character case in which the implementation defines them, header names and values are case-insensitive, and can be submitted or returned in any character case. Other HTTP headers, such as Date, Content-Length, and

Server, are omitted because they are not relevant to the specifics of any example.

The XML version and encoding header

<?xml version="1.0" encoding="UTF-8"?>

is included in example requests but omitted from example responses.

Object IDs shown in href attribute values appear as small integers, for example vapp-7 or org/3. In the

vCloud API that vCloud Director supports, object IDs are universal unique identifiers (UUIDs) as defined by RFC 4122, for example vapp-f5e185a4-7c00-41f1-8b91-0e552d538101 or org/89a1a8f9-

c518-4f53-960c-950db9e3a1fd.

22 VMware, Inc.

Hello vCloud: A Simplified RESTful

Workflow 2

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

This simplified example of a RESTful workflow includes requests that discover and deploy a particular vApp, in this case, an FTP server with a connection to the public Internet.

These examples assume that you have access to a catalog that includes a vApp template with certain characteristics and an organization network that supports connections to the public Internet. The workflow and examples are flexible, and can accommodate various vApp templates and cloud capabilities.

1 Logging In on page 24

vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

2 Find a Catalog and a VDC on page 26

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 Retrieve the Contents of a Catalog on page 27

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

VMware, Inc.

4 Retrieve a Catalog Item on page 28

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 Retrieve Deployment Information From the VDC on page 30

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 Deploy the vApp on page 31

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 Get Information About a vApp on page 34

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.

vCloud API Programming Guide

8 Displaying the Virtual Machine Console on page 37

After a vApp is powered on, you can retrieve a screen ticket from one of its virtual machines. You use that ticket with the VMRC browser plug-in to gain access to the console of the virtual machine.

9 Undeploy, Power Off, and Delete the vApp on page 38

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

10 Log Out on page 40

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

Logging In

vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 43. Because all other vCloud API requests must be authenticated, any vCloud API workflow must begin with a login request that supplies user credentials in the form that Basic HTTP authentication requires.

For information about how to create a login request and view the response, see “Example: Login Request

and Response,” on page 25.

NOTE This procedure assumes that you are logging in with credentials managed by the vCloud Director integrated identity provider. Users whose credentials are managed by a SAML identity provider must follow a different login workflow.

Prerequisites

Verify that the following conditions are met:

You are a member of an organization in the cloud, and have permission to create and operate vApps.

Your organization contains at least one VDC and one network. For more information about setting up

an organization to support the Hello vCloud workflow, see Chapter 6, “Creating and Managing

Organizations,” on page 149.

Your organization contains a catalog in which at least one vApp template is available. For more

information about adding a vApp template to a catalog, see Chapter 4, “Provisioning an Organization,” on page 55.

Procedure

1 Make an API versions request to vCloud Director to obtain the login URL for the REST API.

2 Use the login URL to create a login session.

POST a request to this URL that includes your username, password, and organization name in a MIME Base64 encoding. See “Example: Login Request and Response,” on page 25.

3 Examine the response.

The response code indicates whether the request succeeded, or how it failed.

A successful login request returns an authentication token that you can use in subsequent requests. It also returns a Session element, which contains one or more Link elements, each of which provides a URL that you can use to explore a subset of objects in the cloud. If you log in as a system administrator or organization administrator, this list includes multiple links. See “Example: Create a Login Session Using the

24 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Integrated Identity Provider,” on page 45. Otherwise, the list typically includes a link of type

application/vnd.vmware.vcloud.orgList+xml, as shown in the response portion of “Example: Login

Request and Response,” on page 25. You can use this link to find out more about your organization and

the objects it contains.

For more information about the other links in the Session element, see “Create a Login Session Using the

Integrated Identity Provider,” on page 44.

Example: Login Request and Response

A request to create a login session must supply the user's credentials in the following form:

user@organization:password

user is the user's login name.

organization is the name of an organization of which the user is a member.

password is the user's password.

These credentials must be supplied in a MIME Base64 encoding, as specified in RFC 1421.

NOTE System administrators must log in to the System organization. See “Administrator Credentials and

Privileges,” on page 152. Because the System organization does not support some of the features

demonstrated in the Hello vCloud workflow, you should try this example in another organization.

This example shows a login request and response for a user named HelloUser logging into an organization named ExampleOrg in a cloud whose login URL is https://vcloud.example.com/api/sessions.

Request:

POST https://vcloud.example.com/api/sessions Authorization: Basic encoded-credentials Accept: application/*+xml;version=5.5

Response:

200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.5 ... <Session xmlns="http://www.vmware.com/vcloud/v2.0" user="HelloUser" org="ExampleOrg" ... > <Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"/> <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcloud.example.com/api/query" /> <Link rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcloud.example.com/api/entity/" /> </Session>

VMware, Inc. 25

vCloud API Programming Guide

The response code indicates whether the request succeeded, or how it failed.

If the request is successful, the server returns HTTP response code 200 (OK) and headers that include an

authorization header of the following form:

x-vcloud-authorization: token

This header must be included in each subsequent vCloud API request.

If the authentication header is missing, the server returns HTTP response code 403.

If the credentials supplied in the authentication header are invalid, or if the token has expired, the

server returns HTTP response code 401. The token expires after a configurable interval of client inactivity. The default is 30 minutes after the token is created. After the token expires, you must log in again to obtain a new token.

Find 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.

After you log in, you can make a GET request to your organization's URL to retrieve the XML representation of the organization. This representation shows the organization's attributes and contents, including links to its catalogs and VDCs.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Examine the list of organizations to which you have access.

Make a GET request to the URL in the href value of the orgList link, which is present in the response to all login requests.

GET https://vcloud.example.com/api/org/

Unless you are a system administrator, the response to this request is an OrgList element containing a single Org element, which represents your organization.

2 Retrieve the representation of your organization.

See the request portion of “Example: Retrieve the Contents of an Organization,” on page 26.

3 Examine the response to find the links to the organization's catalogs and VDCs.

See the response portion of “Example: Retrieve the Contents of an Organization,” on page 26.

Example: Retrieve the Contents of an Organization

This example retrieves the ExampleOrg organization listed in the OrgList element shown in Step 1.

26 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Request:

GET https://vcloud.example.com/api/org/5

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="https://vcloud.example.com/api/org/5"> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" name="ExampleCatalog" /> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5" name="ExampleVdc01" /> <Link ... /> <Link ... /> <Description>Example Corp’s Primary Organization</Description> </Org>

Links in the response whose rel attribute has a value of down are references to objects that the organization contains. This example shows the subset of those items that we reference in the Hello vCloud example:

A catalog named ExampleCatalog, at URL https://vcloud.example.com/api/catalog/32, where you can

look for vApp templates.

An organization VDC named ExampleVdc01, at URL https://vcloud.example.com/api/vdc/5, where you

can deploy the vApp.

Retrieve 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.

To use a vApp template or media image listed in a catalog, retrieve the catalog to discover the set of

CatalogItem elements it contains, then make an additional request to retrieve the CatalogItem of interest.

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of your organization.

Use a request like this one:

GET https://vcloud.example.com/api/org/5

VMware, Inc. 27

vCloud API Programming Guide

2 Examine the response to find the links to the organization's catalogs.

These links have the following form:

3 Retrieve the contents of the catalog.

Use a GET request of the form shown in the request portion of “Example: Retrieve the Contents of a

Catalog,” on page 28.

Example: Retrieve the Contents of a Catalog

This example retrieves the catalog shown in the response portion of “Example: Retrieve the Contents of an

Organization,” on page 26.

Request:

GET https://vcloud.example.com/api/catalog/32

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog xmlns="http://www.vmware.com/vcloud/v1.5" name="ExampleCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32"> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="https://vcloud.example.com/api/catalogItem/221"/> <CatalogItem ... /> <CatalogItem ... /> </CatalogItems> </Catalog>

Retrieve 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.

Every vApp template or media image that is added to the catalog is represented as a CatalogItem element. When a client browses a catalog, it can read only the name, type, and href of each CatalogItem. To retrieve an item from the catalog, the client requires more information. In “Example: Retrieve a Catalog Item,” on page 29, the client makes a GET request to the URL in the value of the href attribute of a CatalogItem. The response provides more information, including a description of the referenced object and another URL that the client can use to retrieve a representation of the object.

28 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Prerequisites

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the representation of a catalog in your organization.

Use a request like this one:

GET https://vcloud.example.com/api/catalog/32

2 Examine the response to find the CatalogItem elements that the catalog contains.

The value of the name attribute of a CatalogItem element is taken from the name attribute of the referenced object. You can use it as a preliminary indicator of what the item represents.

3 Retrieve a CatalogItem.

Use a GET request of the form shown in the request portion of “Example: Retrieve a Catalog Item,” on page 29.

Example: Retrieve a Catalog Item

This example retrieves the CatalogItem shown in the response portion of “Example: Retrieve the Contents of

a Catalog,” on page 28.

Request:

GET https://vcloud.example.com/api/catalogItem/221

In addition to the name attribute and Description element, the CatalogItem contains a rel="up" link to the catalog that contains it, and other links that you can use to manage the CatalogItem.

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="Ubuntu Template with vsftpd" id="urn:vcloud:catalogitem:221" href="https://vcloud.example.com/api/catalogItem/221" ... > <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" /> <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/catalogItem/221/metadata" /> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud.example.com/api/catalogItem/221" /> <Link rel="remove" href="https://vcloud.example.com/api/catalogItem/221" /> <Description>Approved template for public FTP sites</Description> <Entity

VMware, Inc. 29

vCloud API Programming Guide

href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> </CatalogItem>

Retrieve 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.

Instantiation, deployment, and operation of a vApp all take place in the context of an organization VDC. The XML representation of a VDC object defines that context in detail. For this exercise, you need several pieces of information from the VDC:

The URL that a client can use to request an instantiateVAppTemplate operation in the VDC.

A list of networks in the organization VDC that the vApp can connect to.

“Example: Deployment Information in a VDC,” on page 30 shows this subset of VDC contents.

Prerequisites

Verify that the following conditions are met:

Verify that you are logged in to the vCloud API as a system administrator or member of an

organization in the cloud.

Retrieve the representation of your organization. See the request portion of “Example: Retrieve the

Contents of an Organization,” on page 26. The response portion contains links to the organization's

VDCs.

Procedure

1 Examine the Org response to find the links to the organization's VDCs.

Links to VDCs have the form:

2 Retrieve the contents of the VDC.

Use a GET request of the form shown in the request portion of “Example: Deployment Information in a

VDC,” on page 30.

Example: Deployment Information in a VDC

This example shows a request to retrieve the XML representation of a VDC. It shows only the subset of the response that contains deployment information.

Request:

GET https://vcloud.example.com/api/vdc/5

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc xmlns="http://www.vmware.com/vcloud/v1.5"

30 VMware, Inc.

+ 340 hidden pages

VMware vCloud Director - 5.5 Programming Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

vCloud API Programming Guide

About the VMware vCloud API 1

Object Taxonomy

Objects, References, and Representations

Links and Link Relations

Client Workflow Overview

vCloud API REST Requests

vCloud API REST Responses

Using the vCloud API with vCloud Director

REST Client Programs

About the Schema Reference

About the vCloud API Examples

Logging In

Find a Catalog and a VDC

Retrieve the Contents of a Catalog

Retrieve a Catalog Item

Retrieve Deployment Information From the VDC