The vCloud API represents objects in a cloud as XML documents in which object properties are contained in elements and attributes that have typed values and an explicit object hierarchy defined by an XML schema.

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.

Each vCloud API object is defined in an XML schema document. Schema files and reference information about all elements, types, operations, and queries is included in the vCloud API Schema Reference. See About the Schema Reference.

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.

All vCloud API requests are processed in the http://www.vmware.com/vcloud/v1.5 XML namespace. vCloud API XML namespace information appears in the values of the xsi:schemaLocation and xmlns attributes in a response document.

xmlns="http://www.vmware.com/vcloud/v1.5"
xsi:schemaLocation="https://vcloud.example.com/api/v1.5/schema/master.xsd"

Other XML namespace identifiers may also be required in request bodies. See XML Namespace Identifiers.

The vCloud XML namespace (http://www.vmware.com/vcloud/v1.5) defines elements and attributes for all supported versions of the vCloud API. Treatment of version-specific elements and attributes in requests is controlled by the value of the version attribute in the Accept header. For example, this Accept header specifies that the request body is presumed to be valid for vCloud API version 5.6 and a version 5.6 response is expected:

Accept: application/*;version=5.6

Requests are validated against the elements and attributes defined in the specified version. Responses are filtered to remove elements and attributes that are not defined in the specified version. 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. The vCloud API Schema Reference indicates the deprecation status of elements and attributes, and also indicates when each element or attribute was added to the API. See About the Schema Reference.

To discover the API versions that a server supports, a client can make an unauthenticated GET request to a well-known URL on the server. See Use the vCloud API with a vCloud Air Virtual Private Cloud OnDemand Instance.

Values of type xs:dateTime are always interpreted as UTC if a timezone has not been explicitly specified.

String values for the name attribute and the Description and ComputerName elements have length limitations that depend on the object to which they are attached.

Length Limits on Element and Attribute String Values

Object

Element or Attribute Name

Maximum Length in Characters

Catalog

name

128

Catalog

Description

256

EdgeGateway

name

35

Media

name

128

Media

Description

256

VApp

name

128

VApp

Description

256

VAppTemplate

name

128

VAppTemplate

Description

256

Vdc

name

256

Vdc

Description

256

Vm

name

128

Vm

ComputerName

15 on Windows, 63 on all other platforms