Using the VMware Cloud Director API with VMware Cloud Director

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

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

Procedure

1. Configure the VMware Cloud Director REST API base URL.
   1. From the top navigation bar, select Administration.
   2. In the left panel, under Settings, click Public Addresses.
   3. Click Edit to customize the public endpoints.
   4. To customize the VMware Cloud Director REST API and OpenAPI URLs, turn off the Use Web Portal Settings toggle.
   5. Enter a custom HTTPS REST API base URL and click Upload to upload the certificates that establish the trust chain for that endpoint.
2. (Optional) Retrieve the list of supported API versions from the server.
   After the VMware Cloud 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.
3. (Optional) If you want to use the vSphere Client to access VMware Cloud Director API objects on a vSphere server, verify that the vSphere Client URL is enabled for all vCenter servers from which you want to retrieve the vSphere URL of an object.

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 VMware Cloud Director. The response, a small subset of which is shown here, includes a VersionInfo element for each API version that this VMware Cloud 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 VMware Cloud Director API. See Logging In.
• For API versions earlier than 5.7, MediaTypeMapping elements for each complex type supported by that version of the VMware Cloud Director 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 VMware Cloud Director. For example, this request retrieves the schema file master.xsd:

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

All VMware Cloud Director 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.