A successful login by an organization or system administrator returns a Session element that contains a link that you can use to retrieve a VCloud element. The VCloud element provides access to a cloud-wide namespace of objects that an organization administrator can view and, in most cases, modify.

The primary administrative objects in a cloud include organizations, provider VDCs, rights, roles, and external networks. Each object type is represented in a VCloud element by zero or more references. The vCloud API defines several objects that are used only in administrative operations. Some, like User, Group, and Role, are unique to administrative operations. Others extend common vCloud API objects to add elements and attributes that only administrators can view or modify. An AdminOrg, for example, provides an administrative view of an Org, and an AdminVdc does the same thing for a Vdc.

A system administrator can obtain more information about any of these objects by making a GET request to its URL, which is the value of its href attribute.

The vCloud element includes links that enable a system administrator to add organizations and roles. Subordinate objects such as users, catalogs, and VDCs are contained by individual organizations and not listed at this level.

Use the credentials of an organization administrator or system administrator to create a login session. See Create a Session Using Basic Authentication.

1

Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session
2

Examine the contents of the Session element to locate the link to the VCloud object.

This link has the following form:

<Link
   rel="down"
   type="application/vnd.vmware.admin.vcloud+xml"
   href="https://vcloud.example.com/api/admin"/>
3

Retrieve the VCloud element by making a GET request to the href value of the Link described in Step 2.

See Example: Retrieve an Administrative View of a Cloud

Request:

GET https://vcloud.example.com/api/admin

Response:

200 OK
Content-Type: application/vnd.vmware.admin.vcloud+xml
...
<VCloud
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="vCloud"
   href="https://vcloud.example.com/api/admin">
   <Link
      rel="add"
      type="application/vnd.vmware.admin.role+xml"
      href="https://vcloud.example.com/api/admin/roles" />
   <Link
      rel="add"
      type="application/vnd.vmware.admin.organization+xml"
      href="https://vcloud.example.com/api/admin/orgs" />
   <Link
      rel="down"
      type="application/vnd.vmware.admin.systemOrganization+xml"
      name="System"
      href="https://vcloud.example.com/api/admin/org/99" />
   <Link ... />
   ...
   <Description>Example Corporation’s vCloud</Description>
   <OrganizationReferences>
     <OrganizationReference
         type="application/vnd.vmware.admin.organization+xml"
         name="Engineering"
         href="https://vcloud.example.com/api/admin/org/1"/>
      <OrganizationReference
         type="application/vnd.vmware.admin.organization+xml"
         name="Engineering"
         href="https://vcloud.example.com/api/admin/org/44"/>
      <OrganizationReference ... />
      ...
   </OrganizationReferences>
   <ProviderVdcReferences>
      <ProviderVdcReference
         type="application/vnd.vmware.admin.providervdc+xml"
         name="Main Provider"
         href="https://vcloud.example.com/api/admin/providervdc/2" />
      <ProviderVdcReference ... />
      ...
   </ProviderVdcReferences>
   <RightReferences>
      <RightReference
         href="https://vcloud.example.com/api/admin/right/4886663f-ae31-37fc-9a70-3dbe2f24a8c5"
         name="Catalog: Add vApp from My Cloud"
         type="application/vnd.vmware.admin.right+xml"/>
      <RightReference
         href="https://vcloud.example.com/api/admin/right/39ec03d4-440d-32cf-8507-f01acd822540"
         name="Catalog: Change Owner"
         type="application/vnd.vmware.admin.right+xml"/>
      ...
      <RightReference
         href="https://vcloud.example.com/api/admin/right/94b041c2-04cd-3a9b-a3ff-0ba57814cff4"
         name="VDC Template: View"
         type="application/vnd.vmware.admin.right+xml"/>
   </RightReferences>
   <RoleReferences>
      <RoleReference
         href="https://vcloud.example.com/api/admin/role/b4d36cd2-7cdd-3cca-8a6c-3bfea3751946"
         name="Defer to Identity Provider"
         type="application/vnd.vmware.admin.role+xml"/>
      <RoleReference
         href="https://vcloud.example.com/api/admin/role/1bf4457f-a253-3cf1-b163-f319f1a31802"
         name="vApp Author"
         type="application/vnd.vmware.admin.role+xml"/>
      ...
      <RoleReference
         href="https://vcloud.example.com/api/admin/role/67e119b7-083b-349e-8dfd-6cf0c19b83cf"
         name="System Administrator"
         type="application/vnd.vmware.admin.role+xml"/>
   </RoleReferences>
   <Networks>
      <Network
         type="application/vnd.vmware.admin.network+xml"
         name="ExternalNetwork-VC1"
         href="https://vcloud.example.com/api/admin/network/7" />
      <Network
         type="application/vnd.vmware.admin.network+xml"
         name="ExternalNetwork-VC2"
         href="https://vcloud.example.com/api/admin/network/33" />
    </Networks>
</VCloud>