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

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.

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.

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

String values for the name attribute, Description element, and ComputerName 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

Vdc

name

256

Vdc

Description

256

VApp

name

128

VApp

Description

256

VAppTemplate

name

128

VAppTemplate

Description

256

Vm

name

128

Vm

ComputerName

15 on Windows, 63 on all other platforms

Catalog

name

128

Catalog

Description

256

Media

name

128

Media

Description

256

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 .

Note

Starting with API version 1.5, requests to all versions of the vCloud API are processed in the http://www.vmware.com/vcloud/v1.5 XML namespace. Treatment of version-specific elements and attributes in requests is controlled by the value of the Accept header. For example, this Accept header specifies that the request body is presumed to be valid for vCloud API version 5.1 and a version 5.1 response is expected:

Accept: application/*+xml;version=5.1

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.

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.

The vCloud API provides complete programmatic access to the vCloud Director Extension Services facility described at vCloud Director Extension Services.

In addition, there is a more general extensibility mechanism, VCloudExtension, that clients are free to use. VCloudExtensibleType is an abstract type that all complex types defined in the vCloud API namespace extend. It can contain an arbitrary number of elements and attributes, and provides a way for you to add custom attributes and elements to any type.

The VCloudExtension element has an attribute named required that specifies how clients and servers proceed when they see an unknown extension. All VCloudExtension elements are assumed to require a server that understands them. The required attribute is optional, but if omitted is assumed to be present with a value of true. This extensibility mechanism allows new servers to extend the XML representations native to the vCloud API without requiring existing clients to understand those extensions.

A client might encounter a VCloudExtension element in any response. If the element declares required=”true” and the client does not know how to interpret the contents of the element, the client can ignore it, but it must include the VCloudExtension in any request to modify the element that contains it. A server must return a failure when a request includes a VCloudExtension element that declares required=”true” but the server does not understand the extension. For more information about VCloudExtension, see the schema reference.