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. 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. |
GET https://vcloud.example.com/api/admin
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/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>