1.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
- Provisioning an Organization with vApps, Templates, and Media
- Deploying and Operating vApps
- Summary of vCloud API vApp and Virtual Machine Operations Requests
- Create a vApp From a Template
- Compose a vApp From Existing Virtual Machines
- Recompose a vApp to Add or Remove Virtual Machines
- Operate a vApp
- Configuring vApps and Virtual Machines
- Retrieve the Configuration Links for a vApp
- Retrieve the Configuration Links for 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
- Creating, Provisioning, and Managing Organizations
- Summary of Administrative Requests
- Administrator Credentials and Privileges
- Organization Administration
- Network Administration
- vDC Administration
- Catalog Administration
- User and Group Administration
- Working With Roles and Rights
- Controlling Access to vApps and Catalogs
- Using vCloud API Extensions to Provision and Manage a Cloud
- Working With Object Metadata
- Using the Query Service
- Configuring and Using Blocking Tasks and Notifications
- XML Representations in the vCloud API
- Index
2 Examine the response, which always includes an HTTP response code and usually includes a body. In the
vCloud API, a response body is an XML representation of an object, including elements and attributes
that represent object properties, links that implement operations on the object or provide references to
contained or containing objects and, if the object is being created or modified, an embedded task object
that tracks the progress of the creation or modification. The response also includes an HTTP response
code, which indicates whether the request succeeded or failed, and might be accompanied by a URL that
points to a location from which you can retrieve additional information.
These operations can repeat, in this order, for as long as necessary.
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 list of vCloud API
versions that the server supports. Each version has its own 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.
Table 1-2. CRUD Operations Summary
Operation Type HTTP Verb Operation Summary
Create POST Creates a new object.
Retrieve GET Retrieves the representation of an
existing object.
Update PUT Modifies an existing object.
Delete DELETE Deletes an existing object.
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 XML
namespace in which to process the request. The following header indicates that
the request is to be processed in the vCloud API 1.5 namespace:
Accept: application/*+xml;version=1.5
Accept-Encoding
By default, vCloud Director returns response content as uncompressed XML.
Compressing the response can improve performance, especially when the
response is large and network bandwidth is a factor. To request a response to
be returned as compressed XML, include the following header:
Accept-Encoding: gzip
vCloud API Programming Guide
16 VMware, Inc.