VMware VCLOUD API 1.0 - TECHNICAL NOTE, Programming Manual

Page: 17 / 212

VMware, Inc. 17
Chapter 1 Introducing the VMware vCloud API
Links provide a way for the server to inform a client about object relationships and the operations that objects
support. For example, a container such as an organization or catalog can return links to the objects it contains,
and a virtual system (a vApp or Vm ) can contain action links that enable operations such as power state changes
or virtual device reconfiguration. Links to actions and contained objects are omitted from responses if the
request was made by a user who has insufficient privileges to access the object or perform the action. Action
links are also omitted when the action cannot be performed (powering on a virtual machine that is already
powered on, for example).
vCloud Client Workflow Overview
Clients of the vCloud API implement a RESTful workflow, making HTTP requests to the server and retrieving
the information they need from the server’s responses.
Requests
Clients make HTTP requests to vCloud URLs, href attribute values which are typically provided by the server
in response to GET requests by the client. Every vCloud has a well ‐ known URL from which a client can get the
server’s login URL and the list of vCloud API versions that the server supports, along with additional
information (see “API Versioning” on page 147). After a client has logged in, all vCloud API URLs can be
discovered by making GET requests to URLs listed in the login response and the URLs contained in responses
to those requests.
Request Headers
All requests from authenticated clients must include an authentication header. See “Authentication” on
page 18.
Requests that include a document body must start with the appropriate HTTP Content ‐ Type header. The type
attribute of a response body indicates the content type of the document. For example, this response fragment
indicates that the content type associated with a CatalogItem entity is
application/vnd.vmware.vcloud.cataxml .
<CatalogItem type="application/vnd.vmware.vcloud.cataxml"
href="http://vcloud.example.com/api/v1.0/catalogItem/221" name="Ubuntu Template with
vsftpd"/>
Any request that includes a CatalogItem requires the following Content ‐ Type header:
Content-Type: application/vnd.vmware.vcloud.cataxml
When it appears as the value of a Content ‐ Type header or the type attribute of an element in the vCloud API,
this string is case ‐ insensitive in requests, and can be returned in either mixed case or lowercase characters in
responses.
For more information, see “Content Type” on page 142.
Request Bodies
This release of Cloud Director uses a validating XML parser that requires elements in a request body to agree
in both order and number with the schema. Request bodies are rejected as invalid unless they meet the
following criteria:

XML namespace attributes must be supplied for all namespaces represented by elements in the request.
See “XML Namespace Identifiers” on page 145.

If multiple namespaces are represented in the request, XML namespace attributes must include an
identifying prefix, and that prefix must be used with elements from that namespace. See “XML
Namespace Prefixes in Request and Response Bodies” on page 146.
N
OTE
When a client uses a link to reference an object, only the href attribute is required. The name and type
are ignored.