When you log in to vCloud Air, you retrieve the Services element, which contains elements for each Compute Service your company has purchased for vCloud Air. Each Service element in the list contains a reference to the service.

Prerequisites

Verify that you are logged in to vCloud Air and assigned to a user role that can access the API.

Invoking the URL for a service reference returns a Compute element. The Compute element includes an attribute for the serviceType and references to all the virtual data centers created within that service.

When the serviceType is a compute:vpc, the Compute element has zero or more virtual data centers. When the serviceType is compute:vpc, the Compute element has one virtual data center.

The reference for each virtual data center (VdcRef) contains the virtual data center name and a link to that virtual data center. Each VdcRef also contains a link to retrieve the vCloud session for that virtual data center.

Procedure
1

Using the Service element returned from the request for the service list, issue a GET request to the URL for the service: 

GET https://vchs.vmware.com/api/vchs/compute/compute-uuid

The returned Compute element contains references to the virtual data centers provisioned for that service. 

<Compute 
...>
   <Link 
   ...>
      <VdcRef 
      ...
         href="https://vchs.vmware.com/api/vchs/compute/compute-uuid}/vdc/vdc-uuid" />
</Compute>
2

Using the VdcRef href, invoke the reference to the virtual data center for which you want to get a session: 

GET href=https://vchs.vmware.com/api/vchs/compute/compute-uuid/vdc/compute-uuid

The returned response contains a reference to retrieve a session for that virtual data center: 

<Vdc 
...>
   <Link rel="down" 
   ...>
      href="https://vchs.vmware.com/api/vchs/compute/compute-uuid/vdc/vdc-uuid/vcloudsession" />
</Vdc>
3

Create a session to the virtual data center by issuing a POST request to the URL in the Vdc element for that virtual data center: 

POST href=https://vchs.vmware.com/api/vchs/compute/compute-uuid/vdc/vdc-uuid/vcloudsession

The returned response includes the session for the virtual data center: 

<VcloudSession 
...>
   <VdcLink
      authorizationToken=vcloud-auth-token
      authorizationHeader="x-vcloud-authorization"
      rel="vcloudvdc" 
      ...
      href="https://vcloud-examplehost1.example.com/api/vdc/vdc-uuid" />
</VcloudSession>

Include the x-vcloud-authorization token in all subsequent API requests as a request header.

4

Issue a GET request to the following URL for the version of the vCloud instance: 

GET https://vcloud-examplehost1.vmware.com/api/versions
Note

You must query the vCloud version before issuing subsequent calls that require setting the correct version header.

The response contains the vCloud version: 

<SupportedVersions 
...
   "https://vcloud-examplehost1.vmware.com/api/versions/schema/versions.xsd">
   <VersionInfo>
      <Version>1.5</Version>
      <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions
      </LoginUrl>
      ...
   </VersionInfo>
   <VersionInfo>
      <Version>5.x</Version>
      <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions
      </LoginUrl>
      ...
   </VersionInfo>
</SupportedVersions>
5

Issue a GET request to the URL for the virtual data center session: 

GET href=https://vcloud-examplehost1.example.com/api/vdc/vdc-uuid

In the request, include the vCloud authorization token (Step step 3) and the vCloud version (Step step 4) by using the following format: 

Authorization: x-vcloud-authorization:vcloud-auth-token
Accept: application/*+xml;version=5.x

The returned response includes the details for the virtual data center. See Response 5 below.

Example: Requests and Responses to Create a Session for a Virtual Data Center

This example shows the five parts (requests and responses) that are required to create a session for a virtual data center located in a vCloud instance.

This example shows a request and response for a Virtual Private Cloud service, with the auto assigned ID 3786bb05-dc9a-471b-91cd-554499d45629, that contains a reference to one virtual data center named 0001-example-vdc-1-public-api. The compute service has UUID vchs-2 and the virtual data center has the UUID vdc-7.

Request 1: 

GET https://vchs.vmware.com/api/vchs/compute/vchs-2
Accept: application/xml;version=5.6

Response 1: 

200 OK
<Compute
   serviceId="example-1101-130711-1"
   serviceType="compute:vpc"
   type="application/xml;class=vnd.vmware.vchs.compute"
   href="https://vchs.vmware.com/api/vchs/compute/vchs-2" 
   ...>
   <Link
      rel="up"
      name="services"
      type="application/xml;class=vnd.vmware.vchs.servicelist"
      href="https://vchs.vmware.com/api/vchs/services" />
   <VdcRef
      status="Active"
      name="0001-example-vdc-1-public-api"
      type="application/xml;class=vnd.vmware.vchs.vdcref"
      href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7">
      <Link
         rel="down"
         name="0001-example-vdc-1-public-api"
         type="application/xml;class=vnd.vmware.vchs.vcloudsession"
         href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7/vcloudsession" />
   </VdcRef>
</Compute>

Request 2: 

GET href=https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7
Accept: application/xml;version=5.6

Response 2: 

200 OK
<Vdc
   name="0001-example-vdc-1-public-api"
   type="application/xml;class=vnd.vmware.vchs.vdcref"
   href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7" 
   ...>
   <Link
      rel="down"
      name="0001-example-vdc-1-public-api"
      type="application/xml;class=vnd.vmware.vchs.vcloudsession"
      href="https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7/vcloudsession" />
</Vdc>

Request 3: 

POST href=https://vchs.vmware.com/api/vchs/compute/vchs-2/vdc/vdc-7/vcloudsession
Accept: application/xml;version=5.6

Response 3: 

201 Created
<VcloudSession name="example-1101-130711-1-session" 
...>
   <VdcLink
      authorizationToken="d6eFLOqQYfuEn2MJTp7BQ2ISEO+ZYaEgTcqBy8wZQ6js="
      authorizationHeader="x-vcloud-authorization"
      rel="vcloudvdc"
      name="example-1101-130711-1"
      href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7" />
</VcloudSession>

Request 4: 

GET https://vcloud-examplehost1.vmware.com/api/versions

Response 4: 

<SupportedVersions 
...
   "https://vcloud-examplehost1.vmware.com/api/versions/schema/versions.xsd">
   <VersionInfo>
      <Version>1.5</Version>
      <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions
      </LoginUrl>
      ...
   </VersionInfo>
   <VersionInfo>
      <Version>5.6</Version>
      <LoginUrl>https://vcloud-examplehost1.example.com/api/sessions
      </LoginUrl>
      ...
   </VersionInfo>
</SupportedVersions>

Request 5: 

GET href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7"
authorizationHeader="x-vcloud-authorization"
authorizationToken="vcloud-auth-token"
Accept: application/*+xml;version=5.6

Response 5:

The response returns a virtual data center object and its attributes. 

<Vdc
   xmlns="http://www.vmware.com/vcloud/v1.5"
   status="1"
   name="0001-example-vdc-1-public-api"
   id="urn:vcloud:vdc:vdc-7"
   type="application/vnd.vmware.vcloud.vdc+xml"
   href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 
   https://vcloud.example.com/api/v1.5/schema/master.xsd">
   <Link
      rel="up"
      type="application/vnd.vmware.vcloud.org+xml"
      href="vcloud-examplehost1.example.com/api/org/vdc-7" />
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.metadata+xml"
      href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7/metadata" />
   <Link
      rel="add"
      type="application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml"
      href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7/action/uploadVAppTemplate" />
   <Link
      rel="add"
      type="application/vnd.vmware.vcloud.media+xml"
      href="https://vcloud-examplehost1.example.com/api/vdc/vdc-7/media" />
   ...
   <AllocationModel>ReservationPool</AllocationModel>
   <ComputeCapacity>
      <Cpu>
         <Units>MHz</Units>
         <Allocated>1000</Allocated>
         <Limit>1000</Limit>
         <Reserved>1000</Reserved>
         <Used>0</Used>
         <Overhead>0</Overhead>
      </Cpu>
      <Memory>
         <Units>MB</Units>
         <Allocated>1024</Allocated>
         <Limit>1024</Limit>
         <Reserved>1024</Reserved>
         <Used>0</Used>
         <Overhead>0</Overhead>
      </Memory>
   </ComputeCapacity>
   <ResourceEntities />
   <AvailableNetworks>
      <Network
         type="application/vnd.vmware.vcloud.network+xml"
         name="0001-example-vdc-1-public-api-default-isolated"
         href="https://vcloud-examplehost1.example.com/api/network/vdc-7" />
   </AvailableNetworks>
   <Capabilities>
      <SupportedHardwareVersions>
         <SupportedHardwareVersion>vmx-04</SupportedHardwareVersion>
         ...
      </SupportedHardwareVersions>
   </Capabilities>
   <NicQuota>0</NicQuota>
   <NetworkQuota>20</NetworkQuota>
   <UsedNetworkCount>0</UsedNetworkCount>
   <VmQuota>0</VmQuota>
   <IsEnabled>true</IsEnabled>
   <VdcStorageProfiles>
      <VdcStorageProfile
         type="application/vnd.vmware.vcloud.vdcStorageProfile+xml"
         name="NFS"
         href="https://vcloud-examplehost1.example.com/api/vdcStorageProfile/vdc-7" />
   </VdcStorageProfiles>
</Vdc>