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.
VMware vFabric Data Director Programming Guide You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com Copyright © 2012 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws.
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 10 Create a Data Director REST Request 11 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 18 Assign a Resource Bundle to an Organization 19 Enable a Base DB Template 19 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 Database Groups organization resource bundle 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.
VMware vFabric Data Director Programming Guide 2 Create a database group. 3 Read available resource templates in the organization. 4 Read available base DB templates in the resource bundle that is assigned to the database group. 5 Read available backup templates of the organization. 6 Create the database. When you later want to delete items, you make corresponding calls in reverse order.
Chapter 1 Data Director API Overview Data Director REST API Workflows Application programs written to a REST API use HTTP requests that are often executed by a script or other higher-level language to make remote procedure calls. These calls create, retrieve, update, or delete objects that the API defines. In the Data Director API, these objects are defined by a collection of XML schemas. The operations themselves are HTTP requests, and are generic to all HTTP clients.
VMware vFabric Data Director Programming Guide 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.
Chapter 1 Data Director API Overview XML: sample sample 1 true JSON: { "name" : "sample", "description" : "sample", "orgId" : 1, "active" : true } VMware, Inc.
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 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.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow 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.
VMware vFabric Data Director Programming Guide 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.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow "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 response that the system returns might look as follows. 202 Accepted location : https://example.aurora.
VMware vFabric Data Director Programming Guide 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. DB parameter groups are associated with base DB templates and contain the database configuration settings that can be used to provision database instances. The database configurations can vary for different database engines. GET https://example.aurora.
Chapter 2 Hello vFabric Data Director: A Simplified RESTful Workflow "dbName": "Aurora_provision", "dbgroupId": 26, "description": "RestApiExample: provision database", "ipWhitelistConfig": { "enabled": true, "ipWhitelistDbIpRange": { "instance": [ { "beginAddress": "10.37.1.1", "description": "ip range", "enabled": true, "endAddress": "10.37.1.100" }, { "beginAddress": "10.37.1.105", "description": "single ip", "enabled": false, "endAddress": "10.37.1.
VMware vFabric Data Director Programming Guide 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 "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. Refresh is supported only for certain clone types.
VMware vFabric Data Director Programming Guide "memoryMb": 3000, "memoryReservationMb": 0, "priority": "Automatic", "storageGb": 10, "swapstorageMb": 4500, "vCpuNumber": 1 } }, "restartIfNeeded": true } The response the system returns might look as follows. content-length : 0 location : https://example.aurora.
Chapter 3 Database Operations Procedure u Perform an HTTP DELETE call. DELETE https://example.aurora.com/datadirector/api/database/45 Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json The response that the system returns might look as follows. content-length : 0 location : https://example.aurora.com/datadirector/api/task/61 202 Accepted VMware, Inc.
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 n action-AfterStorage-Exhausted 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/backu
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 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 10 REST request 11 restore 32 D S database backup 31 creating 21 restore 31 database operations 25 DB group, creating 15, 20 DB groups 8 delete database 28 status codes 35 system resource bundle, creating 15 API call 33 B back up 31 base DB template enabling 15, 16, 19 using with base
VMware vFabric Data Director Programming Guide 38 VMware, Inc.
