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
Client Workflow Overview
vCloud API clients implement a RESTful workflow, making HTTP requests to the server and retrieving the
information they need from the server’s responses.
About RESTful Workflows
REST, an acronym for Representational State Transfer, describes an architectural style characteristic of
programs that rely on the inherent properties of hypermedia to create and modify the state of an object whose
serialized representation is accessible at a URL.
If a URL of such an object is known to a client, the client can use an HTTP GET request to retrieve the
representation of the object. In the vCloud API, this representation is an XML document. In a RESTful
workflow, documents that represent of object state are passed back and forth between a client and a service
with the explicit assumption that neither party need know anything about an object other than what is
presented in a single request or response. The URLs at which these documents are available often persist
beyond the lifetime of the request or response that includes them. The other content of the documents is
nominally valid until the expiration date noted in the HTTP Expires header.
vCloud REST API Workflows
Application programs written to a REST API use HTTP requests that are often executed by a script or other
higher-level language to make remote procedure calls that create, retrieve, update, or delete objects that the
API defines. In the vCloud REST API, these objects are defined by a collection of XML schemas. The operations
themselves are HTTP requests, and so are generic to all HTTP clients.
To write a RESTful client, you must understand only the HTTP protocol and the semantics of XML, the transfer
format that the vCloud API uses. To use the vCloud API effectively in such a client, you need to know only a
few things:
n
What is the set of objects that the API supports, and what do they represent. For example, what is a vDC
and how does it relate to an organization or catalog?
n
How does the API represents these objects. For example, what does the XML schema for an Org look like?
What do the individual elements and attributes represent?
n
How does the client refer to an object on which it wants to operate. For example, where are the links to
objects in a vDC? How does a client obtain and use them?
You can find this information in the vCloud API XML schemas. The XML elements, attributes, and composition
rules defined in these schemas and represent the data structures of objects in the cloud. A client can read an
object by making an HTTP GET request to the object’s URL. A client can create or modify an object with an
HTTP PUT or POST request that includes a new or changed XML body document for the object. A client can
usually delete an object with an HTTP DELETE request.
The vCloud API schema reference includes detailed information about the XML representations of all vCloud
API objects and examples of HTTP requests that operate on those objects. See “About the Schema Reference
Downloadable Archive,” on page 19.
RESTful Workflow Patterns
All RESTful workflows follow a common pattern.
1 Make an HTTP request, typically GET, PUT, POST, or DELETE. The target of this request is either a well-
known URL such as a the vCloud API versions URL, or a URL obtained from the response to a previous
request. For example, a GET request to an organization URL returns links to catalog and vDC objects that
the organization contains.
Chapter 1 About the VMware vCloud API
VMware, Inc. 15