5.5
Table Of Contents
- vCloud API Programming Guide
- Contents
- vCloud API Programming Guide
- About the VMware vCloud API
- Hello vCloud: A Simplified RESTful Workflow
- Exploring a Cloud
- Summary of vCloud API Browsing Requests
- Retrieve the Login URL and List of Supported API Versions
- Create a Login Session Using the Integrated Identity Provider
- Retrieve a List of Organizations Accessible to You
- Retrieve an Administrative View of a Cloud
- Retrieve a List of vSphere Platform Operations and Objects for a Cloud
- Provisioning an Organization
- Summary of vCloud API Provisioning Requests
- Upload an OVF Package to Create a vApp Template
- Download a vApp or vApp Template as OVF
- Upload a Media Image
- Download a Media Image
- Capturing and Importing vApps
- Managing Catalog Items
- Creating and Using Independent Disks
- View or Change the Owner of an Object
- Controlling Access to vApps and Catalogs
- Deploying and Operating vApps
- Summary of vCloud API vApp and Virtual Machine Operations Requests
- Create a vApp From a Template
- Create a vApp From an OVF Package
- Compose a vApp From Existing Virtual Machines
- Recompose a vApp to Add or Remove Virtual Machines
- Clone a vApp
- Capture a vApp as a Template
- Update vApp Access Controls
- Provide User Input Requested by a Virtual Machine
- Attach or Detach an Independent Disk
- Creating and Using vApp Snapshots
- Operate a vApp
- Configuring vApps and Virtual Machines
- Retrieve the Configuration Links for a vApp
- Retrieve the Configuration Links for a Virtual Machine
- Update Multiple Sections of a Virtual Machine
- Retrieve or Update a Modifiable Section
- Update a vApp Network Configuration
- Update the NetworkConnectionSection of a Virtual Machine
- Retrieve or Modify the CPU Configuration of a Virtual Machine
- Retrieve or Modify the GuestCustomizationSection of a Virtual Machine
- Retrieve or Modify ProductSection Elements
- Retrieve or Modify Groups of Related Sections in a Virtual Machine
- Retrieve or Modify the Hard Disk Configuration of a Virtual Machine
- Update the Storage Profile for a Virtual Machine
- Creating and Managing Organizations
- Summary of Administrative Requests
- Administrator Credentials and Privileges
- Organization Administration
- VDC Administration
- Network Administration
- Catalog Administration
- User and Group Administration
- Working With Roles and Rights
- Managing and Monitoring a Cloud
- Summary of System Administration Requests
- Retrieve or Update System Settings
- Attach a vCenter Server
- Finding Available vCenter Resources
- Create a Provider VDC
- Create an External Network
- Create a Network Pool
- Import a Virtual Machine from vCenter
- Relocate a Virtual Machine to a Different Datastore
- Truststore and Keytab Maintenance
- Retrieve the vSphere URL of an Object
- Working With Object Metadata
- Using the Query Service
- Configuring and Using Blocking Tasks and Notifications
- vCloud Director Extension Services
- XML Representations in the vCloud API
- Index
vCloud API REST Requests
To retrieve object representations, clients make HTTP requests to object references. The server supplies these
references as href attribute values in responses to GET requests.
Every cloud has a well-known URL from which an unauthenticated user can retrieve a SupportedVersions
document, which lists each version of the of vCloud API that the server supports. For each version, the
response lists the names and MIME types of the complex types defined in the version's XML namespace,
and the version login URL. A system administrator can use that URL to authenticate to the cloud by logging
in to the System organization. An authenticated user can discover other vCloud API URLs by making GET
requests to URLs retrieved from the login response, and the URLs contained in responses to those requests.
See Chapter 3, “Exploring a Cloud,” on page 41.
Requests are typically categorized in terms of the type of requested operation: create, retrieve, update, and
delete. This sequence of verbs is often abbreviated with the acronym CRUD. Each type of request is
characterized by the use of specific HTTP verb to access a URL found in a Link element that has an
operation-specific value for its rel (relation) attribute.
Table 1‑2. CRUD Operations Summary
Operation Type HTTP Verb Link Relation Operation Summary
Create POST add Creates a new object.
Retrieve GET down Retrieves the representation of an existing object in its current
state.
Update PUT edit Modifies an existing object.
Delete DELETE remove Deletes an existing object. If the object is a container, you must
remove all of its contents before you can delete it.
For example, this Link element indicates that you can use the URL
https://vcloud.example.com/api/admin/org/26 to update the Org object that contains it.
<Link
rel="edit"
type="application/vnd.vmware.admin.organization+xml"
href="https://vcloud.example.com/api/admin/org/26" />
The implied HTTP verb is PUT.
Authentication
HTTP communications between a vCloud API client and server are secured with SSL. The vCloud API also
implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to authenticate
individual HTTP requests by including an authentication header in the request. See “Logging In,” on
page 24.
Request Headers
The following HTTP headers are typically included in vCloud API requests:
Accept
All requests must include an HTTP Accept header that designates the vCloud
API version that the client supports. The following header indicates that the
request is from a vCloud API version 5.5 client:
Accept: application/*+xml;version=5.5
vCloud API Programming Guide
18 VMware, Inc.