vFabric Data Director API clients implement a RESTful workflow, making HTTP requests to the server and retrieving the information they need from the server’s responses.

REST, an acronym for Representational State Transfer, describes a programming style that relies on inherent properties of hypermedia to create and modify the state of an object. The object's serialized representation is accessible as a URL.

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 Data Director API, this representation is an XML document or a JSON object.

In a RESTful workflow, representations of object state are passed back and forth between a client and a service with the explicit assumption that both parties have only the information about an object that 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.

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. These calls create, retrieve, update, or delete objects that the API defines. In the Data Director API, these objects are defined by a collection of XML schemas. The operations themselves are HTTP requests, and are generic to all HTTP clients.

To write a RESTful client, you must understand the HTTP protocol and the semantics of either XML or JSON. You also need an HTTP client, such as Wget. To use the Data Director API effectively with your client code, you can first learn about Data Director by reviewing the vFabric Data Director Administrator and User Guide. You can then learn about the Data Director XML schemas, which are documented for both XML and JSON formats in VMware vFabric Data Director Call Reference . Learn how to answer questions like the following.

What objects does the API support and what do the objects represent. For example, what is a database group and how does it relate to an organization?

How does the API represent these objects. For example, what does the request or response body for an Org object look like? What do the Org object's elements and attributes represent?

How does the client refer to an object on which it wants to operate. For example, where are the links to objects in a database group? How does a client obtain and use them?

Your client code can read an object by making an HTTP GET request to the object’s URL. Your client code can create or modify an object with an HTTP POST or PUT request that includes a new or changed XML or JSON body for the object, and delete an object with an HTTP DELETE request.

All RESTful workflows follow a common pattern.

1

Make an HTTP request, typically GET, PUT, POST, or DELETE. The target of this request is the path to the Data Director API, or a URL obtained from the response to a previous request. For example, a GET request to an organization URL returns Data Director objects that the organization contains.

2

Examine the response, which always includes an HTTP response code and usually includes a body. In the Data Director API, a response body is an XML or JSON 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.