VMware VCLOUD API 1.0 - TECHNICAL NOTE, Programming Manual

Page: 208 / 212

vCloud API Programming Guide
208 VMware, Inc.
example, or the prescribed hierarchy with which elements can be nested) 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 “write” (create or modify) an object with an HTTP PUT or POST request that includes a new or changed
XML body document for the object. And a client can usually delete an object with an HTTP DELETE request.
In this document, we present example requests and responses, and also provide reference information on the
XML schemas that define the request and response bodies.
RESTful Workflow Patterns
All RESTful workflows fall into a pattern that includes only two fundamental operations:

Make an HTTP request (typically GET, PUT, POST, or DELETE). The target of this request is either a
well ‐ known URL (such as the root of a vCloud service or an organization hosted on such a service) or a
link obtained from the response to a previous request. (For example, a GET request to an organization
URL returns links to catalog and vDC objects contained by the organization.)

Examine the response, which always includes an HTTP response code and often includes a body (an XML
document, in the vCloud API). The response body may contain links or other information about the state
of an object. (For example, a response that includes a vApp body contains the details of the vApp’s current
virtual hardware configurations, as well as links that you can use to edit that configuration). If the
response is an HTTP response code, it indicates whether the request succeeded or failed, and may be
accompanied by a URL that points to a location from which additional information can be retrieved.
These two operations can repeat, in this order, for as long as necessary.
For More Information About REST
For a comprehensive discussion of REST from both the client and server perspectives, see:
Richardson, Leonard, and Sam Ruby. RESTful Web Services . North Mankato: O ʹ Reilly Media, Inc., 2007.
There are also many sources of information about REST on the Web, including:

http://www.infoq.com/articles/rest ‐ introduction

http://www.infoq.com/articles/subbu ‐ allamaraju ‐ rest

http://www.stucharlton.com/blog/archives/000141.html