Using the VMware Cloud Director API Schema Reference

 

About the Schema Reference

The VMware Cloud Director API Schema Reference includes reference material for all elements, types, operations, and queries in the VMware Cloud Director API. It also includes the schema definition files and a summary of changes to the schemas in this release.

How the Schema Reference Documentation is Organized

The schema reference documentation is organized to reflect the division of the VMware Cloud Director API into user, administrator, and extension categories. Within each category, you can open a list of elements, types that the elements extend, and operations that create, retrieve, update, or delete the objects that the elements represent. You can also open a list of queries in that category. Reference pages for types and elements are collected in alphabetized folders for browsing. You can also search for schema reference content in the main Documentation Center search window.

User Operations, Elements, Types, and Queries	These operations and queries are accessible to all users who have permission to log into an organization. User elements and user types represent the objects that these operations manipulate.
Administrator Operations, Elements, Types, and Queries	These operations and queries are accessible to organization administrators or system administrators. Administrator elements and types represent the objects that these operations manipulate.
Extension Operations, Elements, Types, and Queries	These operations and queries are accessible to system administrators who need access to vSphere platform objects from the VMware Cloud Director API. Extension elements and types represent the objects that these operations manipulate.

Important

The schema reference includes reference topics for the entire VMware Cloud Director API, including objects and operations that are inaccessible to VMware Cloud Director tenants.

Searching In The Frame Set

In addition to searching using the Documentation Center Search window and navigating using the Documentation Center table of contents, you can also use the Schema Reference frame set, which provides its own search and navigation facilities. You can enter a search string in the Quick Index text box to search the lists of operations, elements, and types in any category.

■

In an Operations list, you can search for the following items: ■ All or part of the name of the object on which you want to operate. The search returns a list of all of the operations that are possible on that object. For example, selecting User Operations and typing vApp in the Quick Index text box returns a list of all of the requests that operate on a vApp object. ■ The name of an action to perform. For example, selecting User Operations and typing power in the Quick Index text box returns a list of all the requests that change the power state of a vApp. ■ An HTTP verb (GET, PUT, POST, DELETE) to view a list of all the requests that use that verb. For example, selecting User Operations and typing PUT in the Quick Index text box returns a list of all of the requests that update an object.

■

In an Elements or Types list, type all or part of the element or type name.

Search terms are not case-sensitive.

Operation Summary Syntax

Operations consist of an HTTP verb and a request URL. The reference documentation represents the verb and the URL using the following syntax:

HTTP_VERB / object_type /{id}[/action/ action_name ]

In this syntax, the initial / character is assumed to follow a site-specific API URL, such as https://vcloud.example.com/api. The following strings represent variables in the remainder of the URL:

HTTP_VERB	The HTTP verb used to request the operation.
object_type	An abbreviation of the MIME type of the object referenced by the operation. This abbreviation is constructed from the final component of the object's media type, between the . and the +xml designation. For example, when an object has media type application/vnd.vmware.vcloud.catalogItem+xml, the object_type is shown as catalogItem. Where the object_type is a virtual machine, it can be represented as either vApp/{id} or vApp/vm-{id}.
{id}	The unique identifier of the object of the operation.
action_name	The name of an action. Required only when the operation request URL includes the string /action/ .

Element and Type Reference Pages

For each element or complex type, the reference documentation provides a page that lists the following items:

Element	The name of the element.
Type	The type of the element.
Namespace	The XML namespace in which this element or type name is defined.
Description	A description of the purpose and contents of the element or type.
Since	The VMware Cloud Director API version in which this element or type first appeared.
Schema	The name of the XML schema definition file in which this element or type is defined. Click to open the file in your browser, or right-click to download it.
Media Type	The MIME type associated with this element or type.
Extends	The abstract base type from which this element's type is derived.
XML Representation	The XML representation of the element or type. Names of contained elements are links to the reference pages for those elements.
Attributes	A table listing the following properties of each attribute of the element or type: Attribute The name of the attribute. Type The primitive XML type of the attribute. Required Yes for attributes that are required. No for attributes that are optional. Modifiable The modification constraint for the attribute value, expressed in one of the following terms: create A client can modify the value on create. update A client can modify the value on update. always A client can modify the value on create or update. none A client cannot modify the value. Since The VMware Cloud Director API version in which this attribute first appeared. Deprecated If use of this attribute is deprecated, the VMware Cloud Director API version in which deprecation was announced. Description A description of the purpose and contents of the attribute. Filter For attributes in query responses, Yes means that this attribute can be used in a query filter expression. Sort For attributes in query responses, Yes means that this attribute can be used with a query sortAsc or sortDesc parameter to sort query results.
Elements	A table listing the following properties of each element defined in the type: Element The name of the element. Type A link to the definition of the complex type that the element is based on. Occurrence The occurrence constraint for the element. The constraint can be one of the following expressions: 0..* Optional. Can occur zero or more times. 0..1 Optional. Can occur at most once. 1 Required. Must occur exactly once. Modifiable The modification constraint for element contents, expressed in one of the following terms: create A client can modify the contents on create. update A client can modify the contents on update. always A client can modify the contents on create or update. none A client cannot modify the contents. Since The VMware Cloud Director API version in which this element first appeared. Deprecated If use of this element is deprecated, the VMware Cloud Director API version in which deprecation was announced. Description A description of the purpose and contents of the element.
Operations	A summary of the operations permitted on the element. Operations are categorized by request type; one of create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD.

Query Reference Pages

Typed queries are are listed by name in alphabetical order. For each query category, the reference documentation provides a page that lists the following items:

Type Name	The name of a query type in this category.
Description	A description of the purpose of the query.
User	YES means that this query is accessible to users.
Admin	YES means that this query is accessible to organization administrators.
System	YES means that this query is accessible to system administrators
Format	Formats supported by the query.
Records Result	The name of the container for the query result, and a link to the reference page for the type that represents each result in the container when the query format is records or idrecords. The type reference page lists all the attributes returned by the query and indicates how each attribute can be used when sorting or filtering query results.
Since	The first VMware Cloud Director API release that supported this query type.
Deprecated	The first VMware Cloud Director API release in which this query type was marked as deprecated.

Schema Definition Files

You can download an archive of XML schema definition files (*.xsd) for the VMware Cloud Director API. The archive includes two folders:

1.5	Schema definition files for VMware Cloud Director API version 1.5 and later.
schemas	Additional schema definition files that are version-independent or from external sources such as DMTF.

Schema Differences in This Release

The VMware Cloud Director API Schema Differences Summary provides information on elements and attributes that are new, changed, or removed in this release.