How it Works
VMware
Loading...
V
Loading...
Loading...
vFabric Data Director - 2.0
Programming Guide
38 pgs513.42 Kb0
Installation Manual
42 pgs666.99 Kb0
Table of contents
Loading...

VMware vFabric Data Director - 2.0 Programming Guide

VMware vFabric Data Director API
Programming Guide
vFabric Data Director 2.0
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-000873-00
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 API Programming Guide 5
1
About the Data Director API 7
2
REST API Versioning 7
Client Workflow Overview 7
Understanding Resources and DB Groups 9
Understanding Call Dependencies 10
Working with Enumeration Types 11
Making a Call 13
3
Data Director REST Requests 13
API REST Response Codes 15
Hello vFabric Data Director: a Simplified RESTful Workflow 17
4
Creating a System Resource Bundle 17
Converting a Base DBVM to a Base DB Template 18
Creating a Resource Bundle 19
Creating an Organization 20
Assigning a Resource Bundle to an Organization 20
Enabling a Base DB Template 21
Creating a DB Group 21
Creating a Database 22
Managing a Database 25
5
Ingesting a Database 29
6
Refreshing a Database or Catalog 31
7
Cloning a Database 33
8
Safeguarding Data 35
9
Backing Up Data 35
Restoring Data 35
Index 37
VMware, Inc. 3
4 VMware, Inc.
vFabric Data Director API
Programming Guide 1

The vFabric Data Director API Programming Guide provides information about version 2.0 of the Data Director API.

VMware provides many different APIs and SDKs for applications and goals. This guide provides information about the vFabric Data Director API for developers who are interested in creating RESTful clients for Data Director.
Revision History
The VMware vFabric Data Director API Programming Guide is revised with each release of the product or when necessary. A revised version can contain minor or major changes.
Table 1-1. Revision History
Revision Date Description
20Mar2012 API Version 1.1
10Jul2012 API Version 2.0
Intended Audience
This guide is intended for software developers who are building Data Director applications, including interactive clients of Data Director. This guide discusses common database terminology, VMware's vFabric Data Director product, VMware's Virtual Machine technology, and web technologies such as XML, HTTP, and REST.
Related Publications
The Data Director Administration Guide contains information about many of the objects and operations referred to in this guide. Most users of the Data Director REST API will find the information in those documents valuable when developing client applications. To access the current versions of these and other VMware books, go to
http://www.vmware.com/support/pubs.
VMware, Inc.
5
6 VMware, Inc.

About the Data Director API 2

The Data Director API provides support for developers who are building interactive clients of vFabric Data Director using a RESTful application development style.
The 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
“Client Workflow Overview,” on page 7
n
“Understanding Resources and DB Groups,” on page 9
n
“Understanding Call Dependencies,” on page 10
n
“Working with Enumeration Types,” on page 11

REST API Versioning

The vFabric Data Director REST API supports versioning through HTTP Accept/Content-Type headers.
As an 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 don't include a version prefix in the Accept header, then the latest version content is returned.

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 an architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and modify the state of an object whose serialized representation is accessible as a URL.
VMware, Inc.
7
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 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.
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 that create, retrieve, update, or delete objects that the API defines. In the Data 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, you must understand only the HTTP protocol, the semantics of either XML or JSON, and an HTTP client, such as Wget. To use the Data Director API effectively with your client code, become familiar with the following:
n
The set of objects that the API supports and what they represent. For example, what is a database group and how does it relate to an organization?
n
How the API represents these objects. For example, what does the request or response body for an Org look like? What do the individual elements and attributes represent?
n
How the client refers 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?
You can find this information in the Data Director API XML schemas. The XML elements, attributes, and composition rules are defined in the XML schemas and represent the data structures of Data Director objects.
You can find this same information for both XML and JSON formats, as they are associated with the API calls, by opening the VMware vFabric Data Director Call Reference (rest-api2.0.html) file and clicking on the respective XML and JSON links.
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. Your client code can 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.
8 VMware, Inc.

Understanding Resources and DB Groups

The Data Director API allows you to perform resource management and access control functions. This section gives you an overview of the available resources and their management operations.
The Data Director API allows you to extend the functionality of the Data Director Client by performing Create, Read, Update, and Delete operations against Data Director organizations, users, roles, database groups, databases, and resource bundles.
In this release of the API, a resource bundle includes one resource pool (cpu/memory), one database storage pool, and one backup storage pool. The following figure represents a default resource pool.
A resource bundle is assigned to or revoked from an organization. The following figure shows the relationship between organizations and resource bundles.
Chapter 2 About the Data Director API
A database group under an organization needs resources to create or backup databases. When creating or backing up a database, the consumed resources come from the parent database group.
The following figure shows the relationship between an organization, a resource bundle, and a database group.
The available resources for a database group are in the resource bundle of the parent organization.
VMware, Inc. 9

Understanding Call Dependencies

Because the Data Director API allows you to manipulate objects and access control, some calls have prerequisite actions. For example, you cannot register a user for an organization before you have created the user.
The following outline gives you an idea of how the calls are related to or dependent on each other.
1 Read qualified resource pools
a Read datastores of a selected resource pool
b Read networks of a selected resource pool
1 Create a resource bundle
2 Create an organization
a Assign the resource bundle to the organization
3 Read available network configurations of the resource bundle
a Create a database group
b Read available resource templates of the organization
c Read available base DB templates of the resource bundle assigned to this database group
d Read available backup templates of the organization
1 Create a database
a Delete a database
2 Delete a database group
4 Revoke the resource bundle from the organization
5 Delete the organization
6 Delete the resource bundle
2 Create a user
a Register/approve/reject a user for an organization
b Create a role for an organization
1 Grant updated permissions to a user in an organization/dbgroup/database
2 Grant updated permissions to a role in an organization/dbgroup/database
3 Grant a role to a user
a Revoke a role from a user
b Revoke permissions from a role
4 Delete a role
5 Unregister a user from an organization
c Disable a user
1 Delete a user
10 VMware, Inc.

Working with Enumeration Types

The vFabric Data Director REST API includes some String parameters that are enumeration types. This section lists most of the enumeration types and the allowed values for each.
Please refer to the VMware vFabric Data Director Call Reference (rest-api2.0.html)for more detailed information when making REST API calls.
Table 2-1. Enumeration Types
Enumeration Type Values Used In
Chapter 2 About the Data Director API
entityType SYSTEM, ORGANIZATION,
DB_GROUP, DB_SERVER, RESOURCE_TEMPLATE BACKUP_TEMPLATE, RESOURCE_BUNDLE
status PENDING, RUNNING, REVERTING,
SUCCESS, FAILED, CANCELLED, ERROR_WAIT
shareLevel/
cpuShareLevel/memShareLevel
priority Automatic, Low, Normal, High DatabaseCreate/resourceSetting/re
type Integer, Boolean, String, Real, Enum All
action-
AfterStorage-
Exhausted
allocType DHCP, IP_POOL ResourceBundle-
extended-RetentionFrequency OneDay, OneWeek, OneMonth,
extended-
RetentionPeriod
HIGH, NORMAL, LOW, CUSTOM DbgroupRead, ResourcePoolRead
Suspend, DeleteOldest DatabaseCreate/backupSetting/bac
ThreeMonths, OneYear
OneWeek, TwoWeeks, OneMonth, SixMonths, OneYear, Forever
api/privilege/entityType
TaskRead
sourceConfig
DatabaseUpdate/resourceSetting/r esourceConfig,
ResourceTemplateRead/resourceC onfig
kupConfig,
DatabaseUpdate/backupSetting/ba ckupConfig,
BackupTemplateRead/backupCon fig
Create/networkSetting/ipAllocTyp es
ResourceBundleUpdate/networkS etting/ipAllocTypes
DatabaseCreate/backupSetting/bac kupConfig,
DatabaseUpdate/backupSetting/ba ckupConfig,
BackupTemplateRead/backupCon fig
DatabaseCreate/backupSetting/bac kupConfig,
DatabaseUpdate/backupSetting/ba ckupConfig,
BackupTemplateRead/backupCon fig
VMware, Inc. 11
Table 2-1. Enumeration Types (Continued)
Enumeration Type Values Used In
snapShotFrequency Never, FourHours, EightHours,
TwelveHours, TwentyHours
snapShot-
Hour, Copy DatabaseCreate/backupSetting/bac
RetentionType
snapShot-
RetentionPeriod
FourHours, EightHours, TwelveHours, TwentyFourHours, FortyEightHours
externalFrequency Never, TwelveHours, OneDay,
OneWeek, OneMonth
externalStartTimeEx Sunday, Monday, Tuesday,
Wednesday, Thursday, Friday, Saturday, Beginning, Middle, End
external-
Retention
OneDay, OneWeek, TwoWeeks, OneMonth, SixMonths, OneYear
DatabaseCreate/backupSetting/bac kupConfig
DatabaseUpdate/backupSetting/ba ckupConfig
BackupTemplateRead/backupCon fig
kupConfig
DatabaseUpdate/backupSetting/ba ckupConfig
BackupTemplateRead/backupCon fig
DatabaseCreate/backupSetting/bac kupConfig
DatabaseUpdate/backupSetting/ba ckupConfig
BackupTemplateRead/backupCon fig
DatabaseCreate/backupSetting/bac kupConfig
DatabaseUpdate/backupSetting/ba ckupConfig
BackupTemplateRead/backupCon fig
DatabaseCreate/backupSetting/bac kupConfig
DatabaseUpdate/backupSetting/ba ckupConfig
BackupTemplateRead/backupCon fig
DatabaseCreate/backupSetting/bac kupConfig
DatabaseUpdate/backupSetting/ba ckupConfig,
BackupTemplateRead/backupCon fig
12 VMware, Inc.
Loading...
+ 26 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use