1.5
Table Of Contents
- vCloud API Programming Guide
- Contents
- vCloud API Programming Guide
- About the VMware vCloud API
- Hello vCloud: A Simplified RESTful Workflow
- Exploring a Cloud
- Provisioning an Organization with vApps, Templates, and Media
- Deploying and Operating vApps
- Summary of vCloud API vApp and Virtual Machine Operations Requests
- Create a vApp From a Template
- Compose a vApp From Existing Virtual Machines
- Recompose a vApp to Add or Remove Virtual Machines
- Operate a vApp
- Configuring vApps and Virtual Machines
- Retrieve the Configuration Links for a vApp
- Retrieve the Configuration Links for a Virtual Machine
- Retrieve or Update a Modifiable Section
- Update a vApp Network Configuration
- Update the NetworkConnectionSection of a Virtual Machine
- Retrieve or Modify the CPU Configuration of a Virtual Machine
- Retrieve or Modify the GuestCustomizationSection of a Virtual Machine
- Retrieve or Modify ProductSection Elements
- Retrieve or Modify Groups of Related Sections in a Virtual Machine
- Retrieve or Modify the Hard Disk Configuration of a Virtual Machine
- Creating, Provisioning, and Managing Organizations
- Summary of Administrative Requests
- Administrator Credentials and Privileges
- Organization Administration
- Network Administration
- vDC Administration
- Catalog Administration
- User and Group Administration
- Working With Roles and Rights
- Controlling Access to vApps and Catalogs
- Using vCloud API Extensions to Provision and Manage a Cloud
- Working With Object Metadata
- Using the Query Service
- Configuring and Using Blocking Tasks and Notifications
- XML Representations in the vCloud API
- Index
XML Representations in the vCloud
API 11
The vCloud API represents objects in a cloud 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. Schema
reference information is available as a download.
Client programs of RESTful Web services must be able to request object representations from the server, parse
the server’s responses to extract the information they contain, and compose requests that, in many cases, are
based on the information extracted from a response. Developers of such clients must understand the structure
of each representation that might be part of a request or response, and any requirements that the network
protocol (HTTP) places on client-server interaction.
Schemas
Each vCloud API object is defined in an XML schema document. Some objects are defined in their own schema
documents. Others are defined in the context of the larger schema in which they are used. Still others are
defined in a common schema document, from which other schemas inherit. Schema files and reference
information about all elements, types, and operations is included in the schema reference download. See
“About the Schema Reference Downloadable Archive,” on page 19.
vCloud Director uses a validating XML parser that requires elements in XML documents to agree in order and
number with the schema. Required elements must appear in request bodies. All elements that appear in request
bodies must appear in the order established by the schema, and with content that conforms to the type
constraint specified in the schema. Default values, where defined, are supplied for elements that are empty.
See “XML Namespace Identifiers,” on page 234.
API Versioning
vCloud API schema version information appears in the values of the xsi:schemaLocation and xmlns attributes
in a response document. For example, a response body that used schema version 1.5 would include the
following attributes:
xmlns="http://www.vmware.com/vcloud/v1.5"
xsi:schemaLocation="https://vcloud.example.com/api/v1.5/schema/master.xsd"
To discover the schema versions that a server supports, a client can make an unauthenticated GET request to
a well-known URL on the server, as shown in “Example: Versions Request and Response,” on page 43.
Extensibility
The vCloud API is designed to be extensible. All complex types that the API defines extend a single abstract
type. This type and all types based on it can include zero or more instances of an extension element that can
contain an arbitrary number of elements and attributes.
VMware, Inc.
233