5.5

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 use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects
between a client and a server. In the vCloud API, these representations are XML documents.
In a RESTful workflow, representations of objects are passed back and forth between a client and a server
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 application, 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
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?
n
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?
n
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 that information in this Guide, and in the vCloud API Schema Reference. See “About the Schema
Reference,” on page 22.
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 document that can contain any of the following items.
n
XML elements and attributes that represent object properties
n
Link elements that implement operations on the object or its contents
n
Iif the object is being created or modified, an embedded Task object that tracks the progress of the
creation or modification
These operations can repeat, in this order, for as long as necessary.
Chapter 1 About the VMware vCloud API
VMware, Inc. 17