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 20.0 and a version 20.0 response is expected:
Accept: application/*;version=20.0
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 Example: Retrieve the Login URL and List of Supported API Versions.
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.
A VM name cannot contain any special characters. See VMware Knowledge Base article https://kb.vmware.com/kb/2046088.
The vCloud API provides complete programmatic access to the vCloud Director Extension Services facility. See 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.