Table of Contents
Advertisement
B
An Introduction to REST for vCloud
API Users
REST, an acronym for Representational State Transfer, is a term that has been widely employed to describe an
architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and
modify the state of an object that is accessible at a URL.
This appendix includes the following topics:
"How REST Works" on page 207
"Using the vCloud REST API" on page 207
"For More Information About REST" on page 208
How REST Works
If a URL of such an object is known to a client, the client can use an HTTP GET request to discover the
properties of the object. These properties are typically communicated in a structured document with an HTTP
Content‐Type of XML or JSON, that provides a representation of the state of the object. In a RESTful workflow,
documents (representations of object state) are passed back and forth (transferred) 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 are often "sticky,"
in that they 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.
Using the vCloud REST API
A "REST API" is in some ways an unfortunate term, since the application programs written to a REST API
actually use HTTP requests (which are often executed by a script or other higher‐level language) as a way of
making what are essentially remote procedure calls that create, modify, or delete the objects defined by the
API. This REST API (and others) is defined by a collection of XML documents that represent the objects on
which the API operates. The operations themselves (HTTP requests) are generic to all HTTP clients.
To write a RESTful client, you need to understand only the HTTP protocol and the semantics of standard
HTML markup. To use the vCloud API effectively in such a client, you need to know three things
the set of objects that the API supports, and what they represent (What is a vDC? How does it relate to an
organization or catalog?)
how the API represents these objects (What does the XML schema for an Org look like? What do the
individual elements and attributes represent?)
how the client refers to an object on which it wants to operate (Where are the links to objects in a vDC?
How does a client obtain and use them?)
To answer these questions, you need to understand the vCloud API XML schemas. These schemas define a
number of XML types, many of which are extended by other types. The vCloud API schemas also use and
extend types defined by the Open Virtualization Format. The XML elements defined in these schemas, along
with their attributes and composition rules (minimum and maximum number of elements or attributes, for
VMware, Inc.
B
207
Advertisement
Table of Contents
