Using the vCloud API with vCloud Director

VMware vCloud Director supports several versions of the vCloud API. You can use a browser or other HTTP client program to send requests and receive responses.

The vCloud Director REST API Reference documentation includes HTML reference material for all XML elements and complex types defined by the vCloud API. It also includes example XML representations. See About the Schema Reference. For information about HTTP client programs to use with vCloud Director, see REST Client Programs.

Procedure

Configure the vCloud Director REST API base URL.
1. Log in to the vCloud Director Web Console as a system administrator.
2. In the vCloud Director Web Console, open System Settings > Public Addresses
3. Type the URL in the HTTPS REST API base URL text box.
4. Upload the SSL certificate chain.
(Optional) Retrieve the list of supported API versions from the server.
After the vCloud Director REST API base URL has been configured, any HTTP client can request a document that lists all the API versions that the server supports. See Retrieve the Login URL and List of Supported API Versions.
(Optional) If you want to use the vSphere Web Client to access vCloud API objects on a vSphere server, verify that the vSphere Web Client URL is enabled for all vCenter servers from which you want to retrieve the vSphere URL of an object.
You can manage this feature on the General tab of the vCenter Properties page of the vCloud Director Web console.

Example: Retrieve the Login URL and List of Supported API Versions

The api/versions request can be made by any client, whether or not the client is authenticated by vCloud Director. The response, a small subset of which is shown here, includes a VersionInfo element for each API version that this vCloud Director installation supports. Each VersionInfo element contains:

A LoginUrl element that contains the URL to which a client can make a login request to access that version of the vCloud API. See Logging In.
For API versions earlier than 5.7, MediaTypeMapping elements for each complex type supported by that version of the vCloud API. This optional element is not returned in the VersionInfo for API version 5.7 and later.

Request:

GET http://vcloud.example.com/api/versions

Response:

200 OK
Content-Type: text/xml
...
<SupportedVersions
   xmlns="http://www.vmware.com/vcloud/versions"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.vmware.com/vcloud/versions
   http://vcloud.example.com/api/versions/schema/versions.xsd">
   <VersionInfo>
      <Version>5.1</Version>
      <LoginUrl>https://vcloud.example.com/api/login</LoginUrl>
      <MediaTypeMapping>
         <MediaType>application/vnd.vmware.vcloud.catalog+xml</MediaType>
         <ComplexTypeName>CatalogType</ComplexTypeName>
         <SchemaLocation>http://vcloud.example.com/api/v1.5/schema/master.xsd</SchemaLocation>
      </MediaTypeMapping>
      <MediaTypeMapping>
         ... 
      </MediaTypeMapping>
      ...
   </VersionInfo>
   <VersionInfo>
      <Version>5.6</Version>
      <LoginUrl>https://vcloud.example.com/api/sessions</LoginUrl>
      <MediaTypeMapping>
         ... 
      </MediaTypeMapping>
      ...
   </VersionInfo>
   <VersionInfo>
      <Version>5.7</Version>
      <LoginUrl>https://vcloud.example.com/api/sessions</LoginUrl>
   </VersionInfo>
</SupportedVersions>

Note: You can use the URL in the SchemaLocation element with a GET request to retrieve the file in which that complex type is defined. This type of request can be made by any client, whether or not the client is authenticated by vCloud Director. For example, this request retrieves the schema file master.xsd:

GET http://vcloud.example.com/api/v1.5/schema/master.xsd

All vCloud API requests are processed in the http://www.vmware.com/vcloud/v1.5 XML namespace. Schema files for all API versions can be retrieved from a .../api/v1.5/... URL.

What to do next

Decide on an HTTP client program to use. See REST Client Programs.