User manual VMWARE VCLOUD API 1.0 API PROGRAMMING GUIDE

[. . . ] vCloud API Programming Guide vCloud API 1. 0 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www. vmware. com/support/pubs. EN-000180-00 vCloud API Programming Guide You can find the most up-to-date technical documentation on the VMware Web site at: http://www. vmware. com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware. com Copyright © 2009, 2010 VMware, Inc. and international copyright and intellectual property laws. [. . . ] vDC administration involves the following objects: A ProviderVdc, which a system administrator creates from vSphere platform resources (see "Create a Provider vDC" on page 127). An AdminVdc, which a system administrator creates to allocate a subset of ProviderVdc resources to a vDC in a specific organization. Organization members see an AdminVdc as a vDC. 102 VMware, Inc. Chapter 6 Administrative Operations Examine the Contents of a Provider vDC ProviderVdc objects are listed among the toplevel objects in a vCloud. in Example 62 on page 94 illustrates such a listing, which includes a ProviderVdcReferences element that contains references to the provider vDCs registered to this vCloud. <ProviderVdcReferences> <ProviderVdcReference type="application/vnd. vmware. admin. providervdc+xml" name="Main Provider" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2"/> <ProviderVdcReference . . . </ProviderVdcReferences> An administrator can use the value of the href attribute in any ProviderVdcReference as the target of a GET request. The response is a ProviderVdc body, as shown in Example 614. Examine the Contents of a Provider vDC Request: GET http://vcloud. example. com/api/v1. 0/admin/providervdc/2 Response: 200 OK Content-Type: application/vnd. vmware. admin. providervdc+xml . . . <ProviderVdc xmlns="http://www. vmware. com/vcloud/v1" status="1" name="PVDC_VC2" type="application/vnd. vmware. admin. providervdc+xml" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2" . . . > <Link rel="up" href="http://vcloud. example. com/api/v1. 0/admin/"/> <Link rel="down" type="application/vnd. vmware. admin. vdcReferences+xml" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2/vdcReferences"/> <Description>PVDC_VC2</Description> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocation>21929</Allocation> <Total>24675</Total> <Used>10053</Used> <Overhead>384</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocation>16207</Allocation> <Total>24475</Total> <Used>15771</Used> <Overhead>977</Overhead> </Memory> </ComputeCapacity> <StorageCapacity> <Units>MB</Units> <Allocation>1311368</Allocation> <Total>2097152</Total> <Used>489361</Used> <Overhead>2436</Overhead> </StorageCapacity> <AvailableNetworks> <Network type="application/vnd. vmware. admin. network+xml" name="External Network VC2" href="http://vcloud. example. com/api/v1. 0/admin/network/54"/> </AvailableNetworks> <IsEnabled>true</IsEnabled> <NetworkPoolReferences> <NetworkPoolReference type="application/vnd. vmware. admin. networkPool+xml" name="VC2-Direct" href="http://vcloud. example. com/api/v1. 0/admin/extension/ networkPool/22"/> VMware, Inc. 103 vCloud API Programming Guide <NetworkPoolReference type="application/vnd. vmware. admin. networkPool+xml" name="VC2_VLAN_Backed" href="http://vcloud. example. com/api/v1. 0/admin/extension/networkPool/2"/> </NetworkPoolReferences> </ProviderVdc> List the Organization vDCs Supported by a Provider vDC An administrator can use the href value from any ProviderVdcReference element in a VCloud as the target of a request that returns a list of organization vDCs that the provider vDC supports. Example 615 shows a request of this type, made using the href of the provider vDC shown in Example 62 on page 94. The response, a VdcReferences element, indicates that the provider vDC at http://vcloud. example. com/api/v1. 0/admin/providervdc/2 is supporting the organization vDC, http://vcloud. example. com/api/v1. 0/admin/vdc/44, created in Example 616. List the Organization vDCs Supported by a Provider vDC Request: GET http://vcloud. example. com/api/v1. 0/admin/providervdc/2/vdcReferences Response: <VdcReferences xmlns="http://www. vmware. com/vcloud/v1" . . . > <Link rel="up" type="application/vnd. vmware. admin. providervdc+xml" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2"/> <VdcReference type="application/vnd. vmware. admin. vdc+xml" name="org3vdc1" href="http://vcloud. example. com/api/v1. 0/admin/vdc/44"/> </VdcReferences> Allocate a vDC to an Organization An organization administrator can allocate resources from a provider vDC to a vDC in an organization by POSTing an AdminVdc body to an organization's add URL for vDCs. Example 64 includes such a URL: <Link rel="add" type="application/vnd. vmware. admin. vdc+xml" href="http://vcloud. example. com/api/v1. 0/admin/org/26/vdcs"/> Example 616 uses that URL to add a new vDC to the organization. The new vDC allocates resources from the provider vDC specified in the ProviderVdcReference element in the request body. The contents of that element were obtained from this element, shown in the response in Example 62. <ProviderVdcReference type="application/vnd. vmware. admin. providervdc+xml" name="MainProvider" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2"/> <ProviderVdcReference . . . Allocate a vDC to an Organization Request: POST http://vcloud. example. com/api/v1. 0/admin/org/26/vdcs Content-Type: application/vnd. vmware. admin. vdc+xml . . . <AdminVdc name="org26vdc1" xmlns="http://www. vmware. com/vcloud/v1"> <Description>Example vDC</Description> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>3072</Allocated> <Limit>4096</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> 104 VMware, Inc. Chapter 6 Administrative Operations <Units>MHz</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Memory> </ComputeCapacity> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd. vmware. admin. providervdc+xml" name="Main Provider" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2"/> </AdminVdc> Response: 201 Created Content-Type: application/vnd. vmware. admin. vdc+xm . . . <AdminVdc name="org26vdc1" type="application/vnd. vmware. admin. vdc+xml" href="http://vcloud. example. com/api/v1. 0/admin/vdc/44" . . . > <Link rel="up" type="application/vnd. vmware. admin. organization+xml" href="http://vcloud. example. com/api/v1. 0/admin/org/26"/> <Link rel="edit" type="application/vnd. vmware. admin. vdc+xml" href="http://vcloud. example. com/api/v1. 0/admin/vdc/44"/> <Link rel="disable" href="http://vcloud. example. com/api/v1. 0/admin/vdc/44/action/disable"/> <Link rel="alternate" href="http://vcloud. example. com/api/v1. 0/vdc/44"/> <Description>Example vDC</Description> <Tasks> <Task status="running" . . . operation="Creating Virtual Datacenter (44)" . . . > . . . </Task> </Tasks> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>3072</Allocated> <Limit>4096</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Memory> </ComputeCapacity> <ResourceEntities/> <AvailableNetworks> <Network type="application/vnd. vmware. admin. network+xml" name="Internet" href="http://vcloud. example. com/api/v1. 0/admin/network/54"/> </AvailableNetworks> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd. vmware. admin. providervdc+xml" name="Main Provider" href="http://vcloud. example. com/api/v1. 0/admin/providervdc/2"/> </AdminVdc> VMware, Inc. 105 vCloud API Programming Guide The response echoes the request, and includes a Task element that tracks creation of the vDC. The network created in Example 610 appears in the AvailableNetworks element. [. . . ] The other content of the documents is nominally valid until the expiration date noted in the HTTP Expires header. Using the vCloud REST API A "REST API" is in some ways an unfortunate term, since the application programs written to a REST API actually use HTTP requests (which are often executed by a script or other higherlevel language) as a way of making what are essentially remote procedure calls that create, modify, or delete the objects defined by the API. This REST API (and others) is defined by a collection of XML documents that represent the objects on which the API operates. The operations themselves (HTTP requests) are generic to all HTTP clients. To write a RESTful client, you need to understand only the HTTP protocol and the semantics of standard HTML markup. [. . . ]