VMware vFabric Data Director Programming Guide vFabric Data Director 2.7 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.
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,2013 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
Contents vFabric Data Director Programming Guide 5 1 Data Director API Overview 7 REST API Versioning 7 Data Director Concepts 8 Understanding Call Dependencies 9 Client Workflow Overview 11 Create a Data Director REST Request 12 2 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 19 Assign a Resource Bundle to an Organization 19 Enable a Base DB Template 20 Cre
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.
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.
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.
Chapter 1 Data Director API Overview Figure 1‑3. Resource Bundles and Organizations organization resource bundle 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. Figure 1‑4.
VMware vFabric Data Director Programming Guide 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.
Chapter 1 Data Director API Overview 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.
VMware vFabric Data Director Programming Guide 2 Examine the response, which always includes an HTTP response code and usually includes a body.
Chapter 1 Data Director API Overview 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 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.
VMware vFabric Data Director Programming Guide n 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.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow 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.
VMware vFabric Data Director Programming Guide 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.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow 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.
VMware vFabric Data Director Programming Guide 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.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow 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.
VMware vFabric Data Director Programming Guide 3 Retrieve information about the base DB templates for the resource bundle that is assigned to DB group in which you want to create the database. GET https://example.aurora.com/datadirector/api/resourcebundle/81/basedbtemplates 4 Retrieve data about the DB parameter groups for the organization that you want to use and the base DB template that you selected in the previous call.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow Example: Create a Database The following example shows all elements of the creation process discussed above together. The example assumes that you created a database group and a base DB template, and assigned the base DB template to a resource template. It also assumes that the template is enabled in the organization to which the database group belongs.
VMware vFabric Data Director Programming Guide "priority": "Automatic", "swapstorageMb": 3000, "vCpuNumber": 1 } }, "diskMapping":{ "instance":[{ "diskName":"data1", "diskSizeGb":15, "datastoreRefId":"null:Datastore:datastore-3803" }] } "takeSnapshotAfterCreation": true } 24 VMware, Inc.
Database Operations 3 Organization administrators might need to perform a variety of database tasks. They can perform the tasks with the vFabric Data Director API.
VMware vFabric Data Director Programming Guide "extendedCreationConfig": { "ingestExternalDb": { "ingestionSource": { "address": "198.51.100.255:/nfs", "catalogStart": "cirrus_11g/BAK6_checkpfile/", "controlFilePath":"c_11g/BAK6_checkpfile/BAK0_1_DIFF_DATA/o1_mf_s_789117626_80l1otww_.bkp", "networkSpeedLimitMb": 100, "optionalPfile": "cirrus_11g/BAK6_checkpfile/initORAC.
Chapter 3 Database Operations }, "cloneTarget": { "cloneBothSchemaAndData": { "fullClone": true } }, "dbgroupId": 26, "description": "RestApiExample: clone database", "name": "Aurora_clone" } The response that the system returns might look as follows. content-length : 0 location : https://example.aurora.com/datadirector/api/task/34 202 Accepted Refresh a Cloned Database You can refresh a cloned database manually, or configure an automatic refresh profile using the vFabric Data Director GUI.
VMware vFabric Data Director Programming Guide { "description": "RestApiExample: reconfigure database", "resourceSetting": { "resourceConfig": { "cpuReservationMHz": 0, "highAvailabilityEnabled": false, "memoryMb": 3000, "memoryReservationMb": 0, "priority": "Automatic", "swapstorageMb": 4500, "vCpuNumber": 1 } }, "diskResizeConfig":{ "instance":[{ "diskId":15, "diskSizeGb":20 }] } } The response the system returns might look as follows. content-length : 0 location : https://example.aurora.
Chapter 3 Database Operations }, "description": "RestApiExample: catalog database", "name": "Aurora_catalog" } The response that the system returns might look as follows. content-length : 0 location : https://example.aurora.com/datadirector/api/task/36 202 Accepted Delete a Database If you have taken care of end of life and backup requirements, you can delete a database, for example, when the database becomes obsolete. You can only delete existing databases. Procedure u Perform an HTTP DELETE call.
VMware vFabric Data Director Programming Guide 30 VMware, Inc.
Safeguarding Data 4 Taking regular backups of your databases is essential to safeguarding your data. Data Director tracks and stores changes for each database on a virtual disk associated with that database. Back up your database to capture the changes, preserve the database, and enable recovering the database and restoring its data after a failure. You can also restore the database to its state at a particular time and replay changes to troubleshoot a problem.
VMware vFabric Data Director Programming Guide Restore Data You can restore a database from one of its backups. Procedure u You can use an HTTP POST call to restore the database. POST https://example.aurora.com/datadirector/api/database/98?action=restore&backupid=3 Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json The response that the system returns might look as follows. 202 Accepted location : https://example.aurora.
Enumeration Types, Status Codes, and Response Code Examples 5 The API includes some String parameters that are enumeration types, and returns status codes. This chapter includes the following topics: n “Enumeration Types,” on page 33 n “Status Codes,” on page 35 n “Response Code Examples,” on page 35 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.
VMware vFabric Data Director Programming Guide Values: Suspend, DeleteOldest Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig n allocType Values: DHCP, IP_POOL Used in: ResourceBundleCreate/networkSetting/ipAllocTypes, ResourceBundleUpdate/networkSetting/ipAllocTypes n extendedRetentionFrequency Values: OneDay, OneWeek, OneMonth, ThreeMonths, OneYear Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSett
Chapter 5 Enumeration Types, Status Codes, and Response Code Examples Status Codes The Data Director API returns a subset of HTTP status codes in the response. Table 5‑1. HTTP Status Codes Status Code Status Description 200 OK The request is valid and was completed. The response includes a document body. 201 Created The request is valid. The requested object was created and can be found at the URL specified in the Location header.
VMware vFabric Data Director Programming Guide 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 36 VMware, Inc.
Index A API call 33 B back up 31 base DB template enabling 15, 16, 20 using with base DBVM 16 base DBVM, converting 15, 16 C catalog database 28 clone database 26 resource bundle assigning 15, 19 creating 15, 17 resources 8 responses, about 35 REST API calls dependencies 9 enumeration types 33 programming style 7 versions 7 workflow 11 REST request 12 restore 32 D S database backup 31 creating 21 restore 31 database operations 25 DB group, creating 15, 20 DB groups 8 delete database 29 status codes
VMware vFabric Data Director Programming Guide 38 VMware, Inc.
