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

VMware vFabric Data Director - 2.0 Programming Guide

Download
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.

Making a Call 3

This section discusses the Data Director REST API requests and responses and gives you some examples.
This chapter includes the following topics:
n
“Data Director REST Requests,” on page 13
n
“API REST Response Codes,” on page 15

Data Director REST Requests

To retrieve object data, you can make HTTP requests to the Data Director API. The server returns the requested data as XML or JSON values in response to POST, GET, PUT, or DELETE requests and the format you specify in the HTTP header.
Creating a Request
As with most REST APIs, you perform the following steps to implement each call.
1. Create a string for the HTTP request that consists of the following format [HTTP verb][url] + [headers] + (optional for some calls) or [Request Body].
2. Authentication. REST APIs accept HTTP Basic authentication on each request, encoded with an existing Data Director username/password credential.
3. Use your programming language to encode the XML or JSON request body, if needed.
4. Use your language's network library (or higher level HTTP library) to send the request to your Data Director http server.
5. Read the response using your programming language.
6. Use your programming language to parse the XML or JSON data within the response.
7. Use the data in your applications.
HTTP/REST Verbs
Each of the HTTP/REST verbs maps to one of the well-known database operations: Create, Retrieve, Update, and Delete (CRUD); or the SQL statements: INSERT, SELECT, UPDATE, and DELETE.
Table 3-1. CRUD Operations Summary
HTTP/REST Operation SQL Statement Operation Summary
POST Create INSERT Creates a new object.
GET Retrieve SELECT Retrieves the representation of an
existing object.
VMware, Inc. 13
Table 3-1. CRUD Operations Summary (Continued)
HTTP/REST Operation SQL Statement Operation Summary
PUT Update UPDATE Modifies an existing object.
DELETE Delete DELETE Deletes an existing object.
Hostname
The hostname is the network name of the computer running Data Director.
Path
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 context-type header is application/xml or application/json, depending on which request format you use. The content-type header must be used with PUT/POST requests that include a request body.
Accepts: The value of the Accepts header is application/xml or application/json, depending on which return format you require. The Accepts header must be used 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.
Request Body
The request body includes the parameters of your API call. The parameter options for each call in the vFabric Data Director API are listed in the VMware vFabric Data Director Call Reference (rest-api2.0.html).
You can retrieve live examples of data object representations in your choice of encoding from a live Data Director API server by browsing the namespace under http://.../datadirector/api/dataformat.
An example of the XML and JSON elements for the request body of the RoleCreate call is shown below.
XML:
<RoleCreate> <name>sample</name> <description>sample</description> <orgId>1</orgId> <active>true</active> </RoleCreate>
JSON:
{ "name" : "sample", "description" : "sample", "orgId" : 1, "active" : true }
See Chapter 4 of this guide for more examples of call requests.
14 VMware, Inc.
Requesting a List
Use the GET verb with any of the ‘Enumerate’ calls (collection URLs). This will return a list of URLs that contain the names of the objects in a collection. Use the GET verb 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.

API REST Response Codes

All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty.
The code sections that follow are examples of Data Director API responses.
Sample response for OrgCreate:
Status: 201 Server: Apache-Coyote/1.1 Location: https://example.aurora.com \ /datadirector/api/org/187 Content-Length: 0 Date: Wed, 07 Mar 2012 03:40:07 GMT
Chapter 3 Making a Call
Sample response for OrgRead
Status: 200 Server: Apache-Coyote/1.1 Cache-Control: private Expires: Thu, 01 Jan 1970 00:00:00 UT Content-Type: application/json Transfer-Encoding: chunked Date: Wed, 07 Mar 2012 03:40:07 GMT {'status':'NORMAL','description': 'Org created by test harness','id': 243,'name':'Test org'}
Sample response for OrgUpdate:
Status: 204 Server: Apache-Coyote/1.1 Cache-Control: private Expires: Thu, 01 Jan 1970 00:00:00 UTC Date: Wed, 07 Mar 2012 03:40:07 GMT
Sample response for OrgDelete:
Status: 202 Server: Apache-Coyote/1.1 Cache-Control: private Expires: Thu, 01 Jan 1970 00:00:00 UTC Location: https://example.aurora.com \ /datadirector/api/task/43 Content-Length: 0 Date: Wed, 07 Mar 2012 03:40:07 GMT
VMware, Inc. 15
Synchronous vs. Asynchronous Responses
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.
Status Codes
The Data Director API returns a subset of HTTP status codes in the response.
Table 3-2. HTTP Status Codes that the Data Director API Returns
Status Code Status Description
200 OK The request is valid and was completed. The response
201 Created The request is valid. The requested object was created and
202 Accepted The request is valid and a task was created to handle it. This
204 No Content The request is valid and was completed. The response does
400 Bad Request The request body is malformed, incomplete, or otherwise
401 Unauthorized An authorization header was expected but not found.
403 Forbidden The requesting user does not have adequate privileges to
404 Not Found One or more objects specified in the request could not be
409 Conflict The object state is not compatible with the requested
500 Internal Server Error The request was received but could not be completed
includes a document body.
can be found at the URL specified in the Location header.
response is usually accompanied by a Location header with a Task URI.
not include a body.
invalid.
access one or more objects specified in the request.
found in the specified container.
operation.
because of an internal error at the server.
16 VMware, Inc.
Hello vFabric Data Director: a
Simplified RESTful Workflow 4
Data Director API clients communicate with Data Director over HTTP, exchanging XML or JSON representations of Data Director API objects. This chapter presents a series of examples that represent a typical Data Director REST API workflow.
These examples describe the tasks you need to perform before and after creating a database with the REST API.
This chapter includes the following topics:
n
“Creating a System Resource Bundle,” on page 17
n
“Converting a Base DBVM to a Base DB Template,” on page 18
n
“Creating a Resource Bundle,” on page 19
n
“Creating an Organization,” on page 20
n
“Assigning a Resource Bundle to an Organization,” on page 20
n
“Enabling a Base DB Template,” on page 21
n
“Creating a DB Group,” on page 21
n
“Creating a Database,” on page 22

Creating a System Resource Bundle

Use this call to create a system resource bundle.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves data about the resource pools.
GET https://example.aurora.com\ /datadirector/api\ /resourcepools?forsysrb=true
From this first call, we learn that the refId of ExampleSysRP is ‘null:ResourcePool:resgroup-9680’, which we use in the next two calls.
The second call retrieves data about the datastores.
GET https://example.aurora.com\ /datadirector/api/resourcepool\ /null:ResourcePool:resgroup-9680\ /datastores
VMware, Inc.
17
The third call retrieves network information.
GET https://example.aurora.com\ /datadirector/api/resourcepool\ /null:ResourcePool:resgroup-9680\ /networks
The final call in the sequence contains a 'payload' of data that you submit to a web service, with the information that we retrieved with our previous queries. This 'payload' is often included as application code in an application such as Python or JavaScript.
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 following is an example of the corresponding response.
202 Accepted location: https://example.aurora.com\ /datadirector/api/task/55

Converting a Base DBVM to a Base DB Template

Use this call to convert a Base DBVM to a Base DB Template.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves the ID of the base DBVMs.
GET https://example.aurora.com\ /datadirector/api/basedbvms
From this call, we can see the data for the base dbvms. We decide to use the base DBVM where the ID is 2.
The final call in the sequence contains a 'payload' of data that you submit to a web service. This is often included as application code in an application such as Python or JavaScript.
POST https://example.aurora.com\ /datadirector/api/basedbtemplates
{ "keepBaseDbvm": true, "baseDbvmId": 2, "name": "vpostgress_template" }
The following is an example of the corresponding response.
202 Accepted location: https://example.aurora.com\ /datadirector/api/task/56
18 VMware, Inc.

Creating a Resource Bundle

Use this call to create a resource bundle.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves data about the resource pools.
GET https://example.aurora.com\ /datadirector/api\ /resourcepools?forsysrb=false
The second call retrieves network information.
GET https://example.aurora.com\ /datadirector/api/resourcepool\ /null:ResourcePool:resgroup-9680\ /networks
The third call retrieves information about the base DB template.
GET https://example.aurora.com\ /datadirector/api/basedbtemplates
Chapter 4 Hello vFabric Data Director: a Simplified RESTful Workflow
From this response, we learn that the template ID is 5.
The final call in the sequence contains a 'payload' of data that you submit to a web service, using information obtained from our previous calls. This is often included as application code in an application such as Python or JavaScript.
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 following is an example of the corresponding response.
202 Accepted location: https://example.aurora.com\ /datadirector/api/task/57
VMware, Inc. 19

Creating an Organization

Use this call to create an organization.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves the adminId from the user information.
GET https://example.aurora.com\ /datadirector/api/users
From the response, we learn that the adminId = 1.
The final call contains a 'payload' of data that you submit to a web service. This is often included as application code in an application such as Python or JavaScript.
This is the request.
POST https://example.aurora.com\ /datadirector/api/orgs
{ "adminId": 1, "name": "AuroraOrg" }
The following is an example of the corresponding response.
201 Created location: https://example.aurora.com\ /datadirector/api/org/82

Assigning a Resource Bundle to an Organization

Use this call to assign a resource bundle to an organization.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves data about the resource bundles.
GET https://example.aurora.com\ /datadirector/api/resourcebundles
The response returns a list of resource bundles. We choose to use the resource bundle with an ID of 81.
The second call retrieves data about the organization.
GET https://example.aurora.com\ /datadirector/api/orgs
The response returns a list of organizations. We choose to use the organization with an ID of 82.
The final call in the sequence performs the assignment operation.
This is an example.
POST https://example.aurora.com\ /datadirector/api/resourcebundle\ /81?action=assign&org=82
Note that this request does not include a 'payload' component.
20 VMware, Inc.
Response
204 No Content

Enabling a Base DB Template

Use this call to enable a database template.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves data about the resource bundles.
GET https://example.aurora.com\ /datadirector/api/resourcebundles
The response returns a list of resource bundles. We choose to use a resource bundle with an ID of 81.
The final call contains a command that enables the base DB template for the resource bundle with ID = 81.
POST https://example.aurora.com\ /datadirector/api/basedbtemplate\ /5?action=enable&rbId=81
The following is an example of the corresponding response.
Chapter 4 Hello vFabric Data Director: a Simplified RESTful Workflow
202 Accepted location: https://example.aurora.com\ /datadirector/api/task/58

Creating a DB Group

Use this call to create a database group.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves data about the resource bundles.
GET https://example.aurora.com\ /datadirector/api/resourcebundles
From the response, we learn that the resource bundle we want to use has an ID of 81.
The second call retrieves data about the organizations.
GET https://example.aurora.com\ /datadirector/api/orgs
From this response, we learn that the organization we want to use has an ID of 82.
The third call uses network information that we already know to retrieve the networkRefId.
GET https://example.aurora.com\ /datadirector/api/resourcepool\ /null:ResourcePool:resgroup-9673\ /networks
VMware, Inc. 21
The final call in the sequence requests the DB Group creation, using a 'payload' of data that you submit to a web service. This is often included as application code in an application such as Python or JavaScript.
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", "share": 100, "limit": -1, "reservationExpandable": false }, "backupStorageAlloc": { "reservation": 50000, "shareLevel": "NORMAL", "share": 100, "limit": -1, "reservationExpandable":false }, "memAlloc": { "reservation": 500, "shareLevel": "NORMAL", "share": 100, "limit": -1, "reservationExpandable": true } }
The following is an example of the corresponding response.
202 Accepted location : https://example.aurora.com\ /datadirector/api/task/59

Creating a Database

Use this call to create a new database.
The call in this example uses an iterative process that is common in REST APIs, where you make a call to retrieve data that you will need in the next call.
The first call retrieves data about the DB Groups.
GET https://example.aurora.com\ /datadirector/api/dbgroups
22 VMware, Inc.
Chapter 4 Hello vFabric Data Director: a Simplified RESTful Workflow
From the response, we learn that the db group we want to use has an ID of 93.
The second call retrieves data about the resource template for the organization with ID = 82 (that we determined in a previous example).
GET https://example.aurora.com\ /datadirector/api/org/82 /resourcetemplates
The response tells us that the resource template we want to use has an ID of 88.
A third call retrieves information about the base DB templates.
GET https://example.aurora.com\ /datadirector/api/basedbtemplates
From the response, we learn that the base DB template we want to use has an ID of 5.
The fourth call retrieves data about the DB parameter groups for the organization with ID = 82 and base DB template ID = 5 (that we determined from the previous calls).
GET https://example.aurora.com\ /datadirector/api/org/82 /basedbtemplate/5/dbparametergroups
From the response, we learn that the DB parameter group we want to use has an ID of 9.
The final call in the sequence contains a 'payload' of data that includes the information that we have retrieved in the previous calls. This is often included as application code.
POST https://example.aurora.com\ /datadirector/api/databases
{ "dbgroupId": 93, "parameterGroupSetting": { "parameterGroupId": 9 }, "name": "Aurora", "dbName": "Aurora", "administratorConfig": { "ownerName": "Aurora", "ownerPassword": "Aurora" }, "resourceSetting": { "resourceTemplateId": 88 }, "baseDbTemplateId":5 }
The following is an example of the corresponding response.
202 Accepted location : https://example.aurora.com\ /datadirector/api/task/6
VMware, Inc. 23
24 VMware, Inc.

Managing a Database 5

This section provides examples of how to perform management tasks on your database using the REST API. These tasks include provisioning, deleting, reconfiguring, and cataloging a database.
Provisioning a Database
In this example, we assume that you have created a DB group, and that the DB Group ID is 26.
The example also assumes that you have created a base DB template with an ID of 1, and assigned it to a resource bundle for DB Group 26. It also assumes that you have enabled the template in the Organization that DB Group 26 belongs to.
The resource template and backup template used in this example are available by default, so you do not have to create them.
Note that a parameterGroupSetting is required when creating a database.
Here is an example of the REST API request to create a database with these assumptions.
POST https://example.aurora.com\ /datadirector/api/databases Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
VMware, Inc.
{ "administratorConfig": { "ownerName": "Aurora", "ownerPassword": "Aurora" }, "backupSetting": { "backupTemplateId": 15 }, "baseDbTemplateId": 1, "dbName": "Aurora_provision", "dbgroupId": 26, "description": "RestApiExample: provision database", "ipWhitelistConfig": { "enabled": true, "ipWhitelistDbIpRange": { "instance": [ { "beginAddress": "10.37.1.1", "description": "ip range",
25
"enabled": true, "endAddress": "10.37.1.100" }, { "beginAddress": "10.37.1.105", "description": "single ip", "enabled": false, "endAddress": "10.37.1.105" } ] } }, "name": "Aurora_provision", "parameterGroupSetting": { "parameterGroupId": 2 }, "resourceSetting": { "resourceConfig": { "cpuReservationMHz": 0, "highAvailabilityEnabled": true, "memoryMb": 2000, "memoryReservationMb": 0, "priority": "Automatic", "storageGb": 10, "swapstorageMb": 3000, "vCpuNumber": 1 } }, "takeSnapshotAfterCreation": true }
The following is an example of the corresponding response.
content-length : 0 location : http://example.aurora.com\ /datadirector/api/task/9
202 Accepted
Deleting a Database
You can only perform this command on an existing database. In this example, the database ID is 25.
Here is an example of the REST API request to delete a database.
DELETE https://example.aurora.com\ /datadirector/api/database/45 Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
The following is an example of the corresponding response.
content-length : 0 location : https://example.aurora.com\ /datadirector/api/task/61
202 Accepted
26 VMware, Inc.
Reconfiguring a Database
You can only perform this command on an existing database. In this example, the database ID is 28.
Here is an example of the REST API request to reconfigure a database.
PUT https://example.aurora.com\ /datadirector/api/database/28 Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
{ "description": "RestApiExample: reconfigure database", "resourceSetting": { "resourceConfig": { "cpuReservationMHz": 0, "highAvailabilityEnabled": false, "memoryMb": 3000, "memoryReservationMb": 0, "priority": "Automatic", "storageGb": 10, "swapstorageMb": 4500, "vCpuNumber": 1 } }, "restartIfNeeded": true }
Chapter 5 Managing a Database
The following is an example of the corresponding response.
content-length : 0 location : https://example.aurora.com\ /datadirector/api/task/29
202 Accepted
Cataloging a Database
You can only perform this command on an existing database. In this example, the database ID is 28.
The example also assumes that you have created the target DB Group and that the DB Group ID is 26.
Here is an example of the REST API request to catalog a database with these parameters.
POST https://example.aurora.com\ /datadirector/api/catalogs Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
{ "cloneParam": { "dstDbgId": 26, "fullClone": true, "srcDbId": 28
VMware, Inc. 27
}, "description": "RestApiExample: catalog database", "name": "Aurora_catalog" }
The following is an example of the corresponding response.
content-length : 0 location : https://example.aurora.com\ /datadirector/api/task/36
202 Accepted
28 VMware, Inc.

Ingesting a Database 6

This section provides examples of how to ingest an existing database into Data Director.
The example also assumes that you have created an Oracle base DB template with an ID of 1, and created a DB Group with an ID of 26.
In this example, the dbName for the ingestion source is ORAC and the ip address is 192.168.64.48:/nfs.
The resourceTemplate used in this example is the default resourceTemplate, so you do not have to create one before making this call.
Here is an example of the REST API request to ingest a database with these assumptions.
POST https://example.aurora.com\ /datadirector/api/databases Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206cGFzc3dvcmQ= Accept : application/json
{ "baseDbTemplateId": 1, "dbName": "ORAC", "dbgroupId": 26, "description": "RestApiExample: ingestion oracle", "extendedCreationConfig": { "ingestExternalDb": { "ingestionSource": { "address": "192.168.64.48:/nfs", "relativePath": "xhwang/BAK1_L0" } } }, "name": "ORAC", "resourceSetting": { "resourceTemplateId": 21 } }
VMware, Inc.
The following is an example of the corresponding response.
content-length : 0 location : https://example.aurora.com\ /datadirector/api/task/221
202 Accepted
29
30 VMware, Inc.

Refreshing a Database or Catalog 7

This call will refresh a catalog or a database from its parent database’s current state.
Refreshing a Database
In this example, we assume that you have a database that was cloned from another database, and the ID of the database clone is 99.
Here is an example of the REST API request to refresh a database from its parent database’s current state, using these assumptions.
POST https://example.aurora.com\ /datadirector/api/database\ /99?action=refresh Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
The following is an example of the corresponding response. This response includes a task in the header that tracks the refresh.
202 Accepted location : https://example.aurora.com\ /datadirector/api/task/79
Refreshing a Catalog
In this example, we assume that you have a catalog that was cloned from a database, and the ID of the catalog is 98.
Here is an example of the REST API request to refresh a catalog from its parent database’s current state, using these assumptions.
POST https://example.aurora.com\ /datadirector/api/catalog\ /98?action=refresh Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
VMware, Inc.
31
The following is an example of the corresponding response. This response includes a task in the header that tracks the refresh.
202 Accepted location : https://example.aurora.com\ /datadirector/api/task/76
32 VMware, Inc.

Cloning a Database 8

This section provides examples of how to clone a database.
You can only perform this command on an existing database. In this example, the database ID is 28.
The example also assumes that you have created the target DB Group and that the DB Group ID is 26.
Here is an example of the REST API request to clone a database with these parameters.
POST https://example.aurora.com\ /datadirector/api/database/28/clones Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
{ "clonePoint": { "cloneNow": {} }, "cloneTarget": { "cloneBothSchemaAndData": { "fullClone": true } }, "dbgroupId": 26, "description": "RestApiExample: clone database", "name": "Aurora_clone" }
VMware, Inc.
The following is an example of the corresponding response.
content-length : 0 location : https://example.aurora.com\ /datadirector/api/task/34
202 Accepted
33
34 VMware, Inc.

Safeguarding Data 9

As with any database system, it is important to safeguard your data by performing backups on a regular schedule.
This section gives you and example of how to backup and restore a database using the REST API.
This chapter includes the following topics:
n
“Backing Up Data,” on page 35
n
“Restoring Data,” on page 35

Backing Up Data

This call will create a snapshot backup for a database.
In this example, we assume that you have created a database, and that the ID of the database is 98.
Here is an example of the REST API request to create a database with these assumptions.
POST https://example.aurora.com\ /datadirector/api/database/98/backups Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
{ "createBackup": { "label": "REST API example", "snapshotBackup": true } }
The following is an example of the corresponding response. This response includes a task in header that tracks the backup.
202 Accepted location : https://example.aurora.com\ /datadirector/api/task/82

Restoring Data

This call restores a database from one of its backups
In this example, we assume that you have created a database, and that the ID of the database is 98. In addition, you have created a backup of the database, and the ID of the backup is 3.
VMware, Inc.
35
Here is an example of the REST API request to create a database with these assumptions.
POST https://example.aurora.com\ /datadirector/api/database\ /98?action=restore&backupid=3 Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json
The following is an example of the corresponding response. This response includes a task in header that tracks the restore.
202 Accepted location : https://example.aurora.com\ /datadirector/api/task/83
36 VMware, Inc.

Index

B
base DB template
enabling 17, 18, 21 using with base DBVM 18
base DBVM, converting 17, 18
C
catalog, refreshing 31
D
database
backup 35 cloning 33 creating 22 ingesting 29 managing 25 refreshing 31 restore 35
DB group, creating 17, 21 DB groups 9
E
enumeration types 11 examples, conventions for 13
V
versions 7
W
workflow
client 7 REST API 7, 17
X
XML
compressed responses 13 validation 13
O
organization
assigning 17 creating 17, 20 resource bundle 20
R
requests, about 13 resource bundle
assigning 17, 20
creating 17, 19 resources 9 responses, about 15
REST API calls
dependencies 10
enumeration types 11
programming style 7
versions 7
workflow 7
S
system resource bundle, creating 17
VMware, Inc. 37
38 VMware, Inc.
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use