VMware vFabric Data Director - 2.5 Programming Guide
VMware vFabric Data Director
Programming Guide
vFabric Data Director 2.5
This document supports the version of each product listed and
supports all subsequent versions until the document is replaced
by a new edition. To check for more recent editions of this
document, see http://www.vmware.com/support/pubs.
EN-001023-00
VMware vFabric Data Director Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual
property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
Contents
vFabric Data Director Programming Guide 5
Data Director API Overview 7
1
REST API Versioning 7
Data Director Concepts 8
Understanding Call Dependencies 9
Client Workflow Overview 10
Create a Data Director REST Request 11
Hello vFabric Data Director: A Simplified RESTful Workflow 15
2
Create a System Resource Bundle 15
Convert a Base DBVM to a Base DB Template 16
Create a Resource Bundle 17
Create an Organization 18
Assign a Resource Bundle to an Organization 19
Enable a Base DB Template 19
Create a Database Group 20
Create a Database 21
Database Operations 25
3
Ingest a Database 25
Clone a Database 26
Refresh a Cloned Database 27
Reconfigure a Database 27
Add a Database to the Catalog 28
Delete a Database 28
Safeguarding Data 31
4
Back Up Data 31
Restore Data 32
Enumeration Types, Status Codes, and Response Code Examples 33
5
Enumeration Types 33
Status Codes 35
Response Code Examples 35
Index 37
VMware, Inc. 3
VMware vFabric Data Director Programming Guide
4 VMware, Inc.
vFabric Data Director Programming Guide
The VMware vFabric Data Director Programming Guide explains how to use the Data Director API.
VMware provides different APIs and SDKs for different applications and goals. This guide has information
for developers who are interested in creating RESTful clients for Data Director.
Revision History
The VMware vFabric Data Director Programming Guide is revised with each release of the product or when
necessary. A revised version can contain minor or major changes.
Table 1. Revision History
Revision Date Description
11Nov2012 API Version 2.5
10Jul2012 API Version 2.0
20Mar2012 API Version 1.1
Intended Audience
This guide is for software developers who are building Data Director applications, including interactive clients
of Data Director. This guide includes a reference to enumerated types, discussions of the sequence of commonly
performed tasks, and examples of tasks.
Related Publications
The vFabric Data Director Administrator and User Guide contains information about many of the objects and
operations referred to in this guide. This information is helpful when you develop a client application using
the Data Director REST API. To access the current version of this publication and other VMware publications,
go to http://www.vmware.com/support/pubs.
VMware, Inc.
5
VMware vFabric Data Director Programming Guide
6 VMware, Inc.
Data Director API Overview 1
The Data Director API allows developers to build interactive clients of vFabric Data Director using a RESTful
application development style.
Data Director API calls communicate over HTTP, exchanging representations of Data Director objects. These
representations are encoded as XML elements or JSON objects, depending on the format of your request.
You use HTTP GET requests to retrieve the current representation of an object, HTTP POST and PUT requests
to create or update an object, and HTTP DELETE requests to delete an object.
This chapter includes the following topics:
n
“REST API Versioning,” on page 7
n
“Data Director Concepts,” on page 8
n
“Understanding Call Dependencies,” on page 9
n
“Client Workflow Overview,” on page 10
n
“Create a Data Director REST Request,” on page 11
REST API Versioning
VMware, Inc.
The vFabric Data Director REST API supports versioning through HTTP Accept/Content-Type headers.
For example, if you want to use the version 2.0 APIs, append the vFabric Data Director version prefix to the
standard media type in the request Accept header.
Accept: application/vnd.vmware.vfdd-v2.0+json
The response will include a versioned Content-Type response header.
Content-Type: application/vnd.vmware.vfdd-v2.0+json
If you do not include a version prefix in the Accept header, then the response returns the latest version.
7
resource bundle
CPU/memory pool
storage pool backup storage pool
resource bundle
organization
VMware vFabric Data Director Programming Guide
Data Director Concepts
The Data Director API supports a significant subset of the functionality that the Data Director UI supports.
The API is especially well suited for performing resource management and access control.
The Data Director API allows you to perform Create, Read, Update, and Delete operations against Data Director
organizations, users, roles, database groups, databases, and resource bundles. The vFabric Data Director
Administrator and User Guide discusses these concepts in detail. This section gives an overview of resource
assignment in the Data Director environment.
1 System administrators create resource bundles to encapsulate CPU and storage resources. In this release
of the API, a resource bundle includes one resource pool, which encapsulates the CPU and memory
resources, one database storage pool, and one backup storage pool.
Figure 1-1. Resource Bundle Contents
2 System administrators define an organization and assign one or more resource bundles to an organization
3 When organization administrators create database groups, they assign one or more resource bundles to
and can also remove resource bundles to ensure an efficient distribution of resources across the company.
Figure 1-2. Resource Bundles and Organizations
each database group. The database group can use the resources to create or back up databases.
8 VMware, Inc.
Figure 1-3. Resource Bundles and Database Groups
resource bundle
organization
database
group
Chapter 1 Data Director API Overview
The database group can only get resources from a resource bundle that is assigned to the database group's
parent organization.
Understanding Call Dependencies
Most of the Data Director calls require as input other objects that you have to retrieve before you make the call.
For example, you cannot register a user for an organization before you have created the user.
This section shows some examples of the sequences of calls for commonly performed tasks.
Create a Resource Bundle
1 Read qualified resource pools.
2 Read the datastores of the selected resource pool.
3 Read the networks for the selected resource pool.
4 Create the resource bundle.
Create an Organization and Assign a Resource Bundle
1 Read qualified resource pools.
2 Read the datastores of the selected resource pool.
3 Read the networks of the selected resource pool.
4 Create a resource bundle.
5 Create an organization.
6 Assign the resource bundle to the organization.
Create a Database
1 Create an organization and assign a resource bundle. See “Create an Organization and Assign a Resource
Bundle,” on page 9 above.
VMware, Inc. 9
VMware vFabric Data Director Programming Guide
2 Create a database group.
3 Read available resource templates in the organization.
4 Read available base DB templates in the resource bundle that is assigned to the database group.
5 Read available backup templates of the organization.
6 Create the database.
When you later want to delete items, you make corresponding calls in reverse order. For example, you delete
all databases that belong to a database group before you delete the database group itself.
Create a User and Grant a Role to the User
If you are working with Data Director users, be aware that Data Director supports two user management
modes.
Global
Organization
To create a user and grant a role to the user, follow these steps.
1 Register or approve the user for an organization.
2 Create a role in the organization.
3 Grant permissions to the user associated with the organization, database group, or database.
4 Grant permissions to the role associated with the organization, database group, or database.
5 Grant the role to the user.
When you later want to delete items, you make corresponding calls in reverse order. For users, you unregister
the user from the organization and you also disable the user before you can delete the user.
All users in the system are visible to all organizations. This mode is best for use
within an enterprise. In Global mode, users do not need to register for an
organization to get a role from that organization.
Users are visible only to the organizations to which they have been granted
access. This mode is best for service providers that host multiple enterprises.
In this mode, users have to register for an organization before they can get a
role from that organization.
Client Workflow Overview
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.
About RESTful Workflows
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.
10 VMware, Inc.
Chapter 1 Data Director API Overview
Data 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. 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.
n
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?
n
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?
n
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.
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 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.
Create a Data Director REST Request
To retrieve object data, you can make HTTP requests to the Data Director API. In response to a POST, GET,
PUT, or DELETE request, the server returns the requested data as XML or JSON values depending on the
format you specify in the HTTP header.
Most REST APIs follow the same sequence of steps to implement a call. If you are already an experienced REST
API user, you can skip this section.
VMware, Inc. 11
VMware vFabric Data Director Programming Guide
Procedure
1 Create a string that has the following format for the HTTP request.
Option Description
HTTP verb
url
headers
POST, GET, PUT, or DELETE.
The URL consists of the host name and the path. The host name is the network
name of the computer that is running Data Director. The path is the path to
the Data Director API package on your computer or network.
The Data Director API supports standard HTTP Accept headers as follows:
what to do
Content-type
Accepts
Authorization:
Location
Either an action or a request body. For simple boolean requests, use an action.
Otherwise, use a request body. See the VMware vFabric Data Director Call
Reference . For examples of object representations, see
http://.../datadirector/api/dataformat.
When you use HTTP GET with any of the Enumerate calls (collection URLs),
the call returns a list of URLs that contain the names of the objects in a
collection. Use HTTP GET again with each of the URLs to retrieve the data
for a specific object. All collection URLs support encoding as application/xml,
application/json, or text/plain media types.
The value of the Content-type header is
application/xml or application/json, depending on
which request format you use. Always use a Contenttype header with PUT or POST requests that include
a request body.
The value of the Accepts header is application/xml
or application/json, depending on the return format
you require. Always use the Accepts header with
GET requests that expect a response body in return.
HTTP basic authentication (RFC 2617).
Requests that create an object, including all
asynchronous requests, which create a task object,
return the created object's URL via this header.
2 Specify authentication information.
REST APIs accept HTTP basic authentication on each request, encoded with an existing Data Director
username and password credential.
3 Encode the XML or JSON request body, if needed.
4 Send the request to your Data Director HTTP server.
5 Read the response and parse the XML or JSON data within the response.
When you receive a 202 Accepted status and a URL, this is an asynchronous response and you must poll
to find out the results of the call. Use GET followed by the URL to retrieve the results of an asynchronous
response.
6 Use the data in your application.
Example: Request Body
The request body of a RoleCreate call can use XML or JSON.
12 VMware, Inc.
Loading...