VMware Cloud Director 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 VMware Cloud Director 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.
VMware Cloud Director 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 VMware Cloud Director 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 VMware Cloud Director API uses. To use the VMware Cloud Director 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 that information in this Guide, and in the VMware Cloud Director API Schema Reference. See About the Schema Reference.
RESTful Workflow Patterns
All RESTful workflows follow a common pattern.
- Make an HTTP request, typically GET, PUT, POST, or DELETE. The target of this request is either a well-known URL such as the VMware Cloud Director 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.
- Examine the response, which always includes an HTTP response code and usually includes a body. In the VMware Cloud Director API, a response body is an XML document that can contain any of the following items.
- XML elements and attributes that represent object properties
- Link elements that implement operations on the object or its contents
- If 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.
