VMware vFabric Data Director 2.5 User guide

Brand: VMware

Model: vFabric Data Director 2.5

Category: Software manuals

Type: User 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

2 VMware, Inc.

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:

[email protected]

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

Contents

vFabric Data Director Programming Guide 5

Data Director API Overview 7

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

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

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

Back Up Data 31

Restore Data 32

Enumeration Types, Status Codes, and Response Code Examples 33

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.

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:

“REST API Versioning,” on page 7

“Data Director Concepts,” on page 8

“Understanding Call Dependencies,” on page 9

“Client Workflow Overview,” on page 10

“Create a Data Director REST Request,” on page 11

REST API Versioning

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.

VMware, Inc.

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

resource bundle

CPU/memory pool

storage pool backup storage pool

2 System administrators define an organization and assign one or more resource bundles to an organization

and can also remove resource bundles to ensure an efficient distribution of resources across the company.

Figure 1-2. Resource Bundles and Organizations

resource bundle

organization

3 When organization administrators create database groups, they assign one or more resource bundles to

each database group. The database group can use the resources to create or back up databases.

VMware vFabric Data Director Programming Guide

8 VMware, Inc.

Figure 1-3. Resource Bundles and Database Groups

resource bundle

organization

database

group

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.

Chapter 1 Data Director API Overview

VMware, Inc. 9

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

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.

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.

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.

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.

VMware vFabric Data Director Programming Guide

10 VMware, Inc.

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.

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.

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.

Chapter 1 Data Director API Overview

VMware, Inc. 11

Procedure

1 Create a string that has the following format for the HTTP request.

Option Description

HTTP verb

POST, GET, PUT, or DELETE.

url

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.

headers

The Data Director API supports standard HTTP Accept headers as follows:

Content-type

The value of the Content-type header is

application/xml or application/json, depending on

which request format you use. Always use a Content-

type header with PUT or POST requests that include

a request body.

Accepts

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.

Authorization:

HTTP basic authentication (RFC 2617).

Location

Requests that create an object, including all

asynchronous requests, which create a task object,

return the created object's URL via this header.

what to do

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.

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.

VMware vFabric Data Director Programming Guide

12 VMware, Inc.

XML:

<name>sample</name>

<description>sample</description>

</RoleCreate>

JSON:

{

"name" : "sample",

"description" : "sample",

"orgId" : 1,

"active" : true

}

Chapter 1 Data Director API Overview

VMware, Inc. 13

VMware vFabric Data Director Programming Guide

14 VMware, Inc.

Hello vFabric Data Director: A

Simplified RESTful Workflow 2

Data Director API clients communicate with Data Director over HTTP, exchanging XML or JSON

representations of Data Director API objects.

The simplified RESTful workflow example illustrates the tasks that you need to perform to create a database

with the REST API. For each task, you must have the appropriate permissions.

This chapter includes the following topics:

“Create a System Resource Bundle,” on page 15

“Convert a Base DBVM to a Base DB Template,” on page 16

“Create a Resource Bundle,” on page 17

“Create an Organization,” on page 18

“Assign a Resource Bundle to an Organization,” on page 19

“Enable a Base DB Template,” on page 19

“Create a Database Group,” on page 20

“Create a Database,” on page 21

Create a System Resource Bundle

The system resource bundle provides CPU, memory, network, and storage resources for the base database

virtual machines (base DBVMs) and base database templates that you use to create and provision databases.

Each Data Director installation must have one system resource bundle.

You create the system resource bundle before setting up other Data Director entities and populate the resource

bundle with base database templates and base DBVMs.

Prerequisites

Create a resource pool to use for allocating CPU and memory resources. Resource pools are part of the

underlying vSphere environment. You can create them using the vSphere Client, the vSphere Web Client,

or the vSphere SDK.

Decide on the storage resources that you want to include in the resource bundle. Plan for storage resources

for database storage and resources for backup storage.

Decide on the base DB template that you want to assign to the resource bundle. Organization users can

create and provision databases only when base DB templates are assigned to, and enabled in, an

organization's resource bundle or resource bundles. You can assign additional base DB templates to

resource bundles at any time. “Convert a Base DBVM to a Base DB Template,” on page 16 explains how

to create a base DB template.

VMware, Inc.

Decide on the networking resources that you want to include in the resource bundle. The resource bundle's

networking resources are used for the DB access network for the databases in an organization.

Procedure

1 Retrieve data about the resource pools.

GET https://example.aurora.com/datadirector/api/resourcepools?forsysrb=true

From this first call, you learn that the refId of ExampleSysRP is null:ResourcePool:resgroup-9680. You

use the refID in the next two calls.

2 Retrieve information about the datastores associated with the system resource pool.

GET https://example.aurora.com/datadirector/api/resourcepool/

null:ResourcePool:resgroup-9680/datastores

3 Retrieve network information associated with the system resource pool.

GET https://example.aurora.com/datadirector/api/resourcepool/

null:ResourcePool:resgroup-9680/networks

You can now allocate the system resource pool on the datastore using the network information you

retrieved. The HTTP POST call includes payload data that might be included as application code in an

application such as Python or JavaScript.

4 Create the system resource bundle.

POST https://example.aurora.com/datadirector/api/sysresourcebundle

{

"networkRefId": "null:Network:network-1464",

"backupDataStoreRefId": "null:Datastore:datastore-3803",

"dataDataStoreRefId": "null:Datastore:datastore-3803",

"backupStorageSize": 0,

"dataStorageSize": 151200,

"resourcePoolRefId": "null:ResourcePool:resgroup-9680",

"ipAllocType": "DHCP"

}

The response that the system returns might look as follows.

202 Accepted location: https://example.aurora.com/datadirector/api/task/55

What to do next

Convert a base DBVM to a base DB template.

Convert a Base DBVM to a Base DB Template

Data Director uses base database templates (base DB templates) to create databases. A base DB template is a

virtual machine that contains all the software required to create a database. Required software includes the

operating system (OS), database, and system software configurations. The base DB template can also contain

third-party tools that are required for a particular environment.

Create a base DB template from a database virtual machine (DBVM). A DBVM is a virtual machine with a disk

layout that contains the seven virtual machine disks (VMDK) required for base DBVMs to work in Data

Director. See vFabric Data Director Administrator and User Guide.

Prerequisites

Create a system resource bundle. See “Create a System Resource Bundle,” on page 15.

VMware vFabric Data Director Programming Guide

16 VMware, Inc.

Procedure

1 Retrieve the IDs of the base DBVMs.

GET https://example.aurora.com/datadirector/api/basedbvms

The call returns the data for the base DBVMs. If you decide to use the base DBVM with ID 2 to create a

base DB template, you can make an HTTP POST call to create the base DB template.

2 Create the base DB template.

POST https://example.aurora.com/datadirector/api/basedbtemplates

{

"keepBaseDbvm": true,

"baseDbvmId": 2,

"name": "vpostgress_template"

}

The response that the system returns might look as follows.

202 Accepted

location: https://example.aurora.com/datadirector/api/task/56

What to do next

Create a resource bundle.

Create a Resource Bundle

Resource bundles allow you to bundle CPU, memory, storage, database template, and networking resources.

You create resource bundles from resource pools.

Prerequisites

Create a resource pool to use for allocating CPU and memory resources. Resource pools are part of the

underlying vSphere environment, you can create them using the vSphere Client, the vSphere Web Client,

or the vSphere SDK. See vFabric Data Director Administrator and User Guide for information on cluster and

resource pool requirements for Data Director.

Decide on the storage resources that you want to include in the resource bundle. Plan for storage resources

for database storage and resources for backup storage.

Decide on the base DB template that you want to assign to the resource bundle. Organization users can

create and provision databases only when base DB templates are assigned to, and enabled in, an

organization's resource bundle or resource bundles. You can assign additional base DB templates to

resource bundles at any time. “Convert a Base DBVM to a Base DB Template,” on page 16 explains how

to create a base DB template.

Decide on the networking resources that you want to include in the resource bundle. The resource bundle's

networking resources are used for the DB access network for databases in an organization.

Procedure

1 Retrieve data about available resource pools; excluding the system resource pool.

GET https://example.aurora.com/resourcepools?forsysrb=false

2 Retrieve network information.

GET https://example.aurora.com/datadirector/api/resourcepool/

null:ResourcePool:resgroup-9680/networks

3 Retrieve information about the base DB templates.

GET https://example.aurora.com/datadirector/api/basedbtemplates

Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow

VMware, Inc. 17

You learn that the template ID for the base DB template is 5.

You can now make an HTTP POST call that includes payload data. The payload data might be included

as application code in a Python or JavaScript application.

4 Create the resource bundle by making an HTTP POST call and specifying network settings, storage

settings, the base DB template, and other attributes.

POST https://example.aurora.com/datadirector/api/resourcebundles

{

"networkSetting": {

"instance": [{

"networkRefId": "null:Network:network-1464","ipAllocType": "DHCP"

}]

"dataDataStoreRefId": "null:Datastore:datastore-3803",

"name": "AuroraRB",

"minStorageAlpha": 1.0,

"dataStorageSize": 100000,

"backupDataStoreRefId": "null:Datastore:datastore-3803",

"baseDbTemplateId": {

"instance": [{

"templateId": 5

}]

"resourcePoolRefId": "null:ResourcePool:resgroup-9673",

"backupStorageSize": 100000

}

The response that the system returns might look as follows.

202 Accepted location: https://example.aurora.com/datadirector/api/task/57

What to do next

Create an organization.

Create an Organization

The Data Director hierarchy consists of organizations, each with its own discrete database groups and

databases. You create organizations to allow organization administrators independent management of their

database groups and databases.

Prerequisites

Create one or more resource bundles to allocate to the organization. See “Create a Resource Bundle,” on

page 17.

Procedure

1 Retrieve the available administrator IDs so you can use the ID to specify the administrator for the

organization.

GET https://example.aurora.com/datadirector/api/users

VMware vFabric Data Director Programming Guide

18 VMware, Inc.

2 Make an HTTP POST call to create the organization.

POST https://example.aurora.com/datadirector/api/orgs

{

"adminId": 1,

"name": "AuroraOrg"

}

The response that the system returns might look as follows.

202 Created location: https://example.aurora.com/datadirector/api/org/82

What to do next

Assign a resource bundle to the organization.

Assign a Resource Bundle to an Organization

Before the organization administrator can create a database in the organization, the system administrator has

to assign a resource bundle to the organization.

Prerequisites

Create a resource bundle. See “Create a Resource Bundle,” on page 17.

Create an organization. See “Create an Organization,” on page 18.

Procedure

1 Retrieve a list of all resource bundle IDs.

GET https://example.aurora.com/datadirector/api/resourcebundles

2 Retrieve a list of all organization IDs.

GET https://example.aurora.com/datadirector/api/orgs

3 Assign one of the resource bundles to one of the organizations.

POST https://example.aurora.com/datadirector/api/resourcebundle/81?action=assign&org=82

This call performs an assign action and does not include payload data. The response might look like the

following.

204 No Content

What to do next

Enable a base DB template.

Enable a Base DB Template

Organization administrators enable a base DB template on the underlying resource bundles so that

organization users can provision databases based on the base DB template.

Prerequisites

Assign at least one base DB template to the resource bundles of the organization. See “Assign a Resource Bundle

to an Organization,” on page 19.

Procedure

1 Retrieve a list of resource bundles.

GET https://example.aurora.com/datadirector/api/resourcebundles

Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow

VMware, Inc. 19

2 Enable the base DB template for the resource bundle with the ID you select, in this example, 81.

POST https://example.aurora.com/datadirector/api/basedbtemplate/5?action=enable&rbId=81

This call performs an assign action and does not include payload data. The response might look like the

following.

202 Accepted location: https://example.aurora.com/datadirector/api/task/58

What to do next

Create a database group.

Create a Database Group

Database groups contain sets of databases within an organization. Database groups enable grouping of related

databases and provide efficient use of resources that are needed to provision and operate databases.

Prerequisites

Assign at least one resource bundle to the organization where you want to create a database group. See

“Assign a Resource Bundle to an Organization,” on page 19.

Enable at least one base DB template in the organization. See “Enable a Base DB Template,” on page 19.

Procedure

1 Retrieve the list of resource bundles and look for the ID of the resource bundle that you want to use.

GET https://example.aurora.com/datadirector/api/resourcebundles

2 Retrieve the list of organizations and look for the ID of the organization that you want to use.

GET https://example.aurora.com/datadirector/api/orgs

3 Retrieve the network information for the resource pool.

Because Data Director does not have the resource pool ID, you access it indirectly.

GET https://example.aurora.com/datadirector/api/resourcepool/

null:ResourcePool:resgroup-9673/networks

4 Create the database group using the resource bundle, organization, and network information that you

retrieved.

The HTTP POST call includes payload data that might be included as application code in a Python or

JavaScript application.

POST https://example.aurora.com/datadirector/api/dbgroups

{

"cpuAlloc": {

"reservation": 500,

"shareLevel": "NORMAL",

"share": 100,

"limit": -1,

"reservationExpandable": true

"networkRefId": "null:Network:network-1464",

"resourceBundleId": 81,

"name": "AuroraDbgroup",

"organizationId": 82,

"dataStorageAlloc": {

"reservation": 50000,

"shareLevel": "NORMAL",

VMware vFabric Data Director Programming Guide

20 VMware, Inc.

Page is loading ...

VMware vFabric Data Director 2.5 User guide

Brand: VMware

Model: vFabric Data Director 2.5

Category: Software manuals

Type: User guide

Download PDF

report

VMware vFabric Data Director 2.5 User guide

VMware vFabric Data Director 2.5 User guide

Related papers

Other documents