The VMware Cloud Director 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.
XML Schemas
Each VMware Cloud Director 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 VMware Cloud Director API Schema Reference. See About the Schema Reference.
VMware Cloud 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.
http://www.vmware.com/vcloud/v1.5 XML namespace.
VMware Cloud Director 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.
API Versions
http://www.vmware.com/vcloud/v1.5) defines elements and attributes for all supported versions of the
VMware Cloud Director 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
VMware Cloud Director API version 20.0 and a version 20.0 response is expected:
Accept: application/*;version=20.0Requests 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 VMware Cloud Director API that is less than or equal to the version specified in the
Accept header. Exceptions to this rule are mentioned in the
VMware Cloud Director
Release Notes. The
VMware Cloud Director 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 Retrieve the Login URL and List of Supported API Versions#GUID-8084EE5C-CD8C-4CB7-81FD-D75569C5DF14.
Date and Time Values
Values of type xs:dateTime are always interpreted as UTC if a timezone has not been explicitly specified.
Length Limits on Element and Attribute String Values
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.
| 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 |
A VM name cannot contain any special characters. See VMware Knowledge Base article https://kb.vmware.com/kb/2046088.
Extensibility
The VMware Cloud Director API provides complete programmatic access to the VMware Cloud Director Extension Services facility. See VMware Cloud Director Extension Services. See the VMware Cloud Director API Programming Guide.
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 VMware Cloud Director 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 VMware Cloud Director 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.
