User`s guide

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, representations 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:

The set of objects that the API supports, and what they represent; for example, what is a vDC and how

does it relate to an organization or catalog?

How 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?

How a client refers 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 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,” on page 17.

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 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.

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.

Chapter 1 About the VMware vCloud API

VMware, Inc. 15