VMware vfabric Data Director Programming Guide

Transcription

1 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 EN

2 VMware vfabric Data Director Programming Guide You can find the most up-to-date technical documentation on the VMware Web site at: The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: 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 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 Hillview Ave. Palo Alto, CA VMware, Inc.

3 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 Create a Database Group 20 Create a Database 21 3 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 4 Safeguarding Data 31 Back Up Data 31 Restore Data 32 5 Enumeration Types, Status Codes, and Response Code Examples 33 Enumeration Types 33 Status Codes 35 Response Code Examples 35 Index 37 VMware, Inc. 3

4 VMware vfabric Data Director Programming Guide 4 VMware, Inc.

5 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 Jul2012 API Version Mar2012 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 VMware, Inc. 5

6 VMware vfabric Data Director Programming Guide 6 VMware, Inc.

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

8 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. 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 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. 8 VMware, Inc.

9 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. 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. VMware, Inc. 9

10 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. 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 Organization 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. 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. 10 VMware, Inc.

11 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. 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. VMware, Inc. 11

12 VMware vfabric Data Director Programming Guide Procedure 1 Create a string that has the following format for the HTTP request. Option HTTP verb url headers Description POST, GET, PUT, or DELETE. 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. The Data Director API supports standard HTTP Accept headers as follows: Content-type Accepts The value of the Content-type header is application/xml or application/json, depending on which request format you use. Always use a Contenttype header with PUT or POST requests that include a request body. 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 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. 12 VMware, Inc.

13 Chapter 1 Data Director API Overview XML: <RoleCreate> <name>sample</name> <description>sample</description> <orgid>1</orgid> <active>true</active> </RoleCreate> JSON: { "name" : "sample", "description" : "sample", "orgid" : 1, "active" : true VMware, Inc. 13

14 VMware vfabric Data Director Programming Guide 14 VMware, Inc.

15 Hello vfabric Data Director: A 2 Simplified RESTful Workflow 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. 15

16 VMware vfabric Data Director Programming Guide 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 From this first call, you learn that the refid of ExampleSysRP is null:resourcepool:resgroup You use the refid in the next two calls. 2 Retrieve information about the datastores associated with the system resource pool. GET null:resourcepool:resgroup-9680/datastores 3 Retrieve network information associated with the system resource pool. GET 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 { "networkrefid": "null:network:network-1464", "backupdatastorerefid": "null:datastore:datastore-3803", "datadatastorerefid": "null:datastore:datastore-3803", "backupstoragesize": 0, "datastoragesize": , "resourcepoolrefid": "null:resourcepool:resgroup-9680", "ipalloctype": "DHCP" The response that the system returns might look as follows. 202 Accepted location: 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 VMware, Inc.

17 Chapter 2 Hello vfabric Data Director: A Simplified RESTful Workflow Procedure 1 Retrieve the IDs of the base DBVMs. GET 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 { "keepbasedbvm": true, "basedbvmid": 2, "name": "vpostgress_template" The response that the system returns might look as follows. 202 Accepted location: 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 2 Retrieve network information. GET null:resourcepool:resgroup-9680/networks 3 Retrieve information about the base DB templates. GET VMware, Inc. 17

18 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 { "networksetting": { "instance": [{ "networkrefid": "null:network:network-1464","ipalloctype": "DHCP" ], "datadatastorerefid": "null:datastore:datastore-3803", "name": "AuroraRB", "minstoragealpha": 1.0, "datastoragesize": , "backupdatastorerefid": "null:datastore:datastore-3803", "basedbtemplateid": { "instance": [{ "templateid": 5 ], "resourcepoolrefid": "null:resourcepool:resgroup-9673", "backupstoragesize": The response that the system returns might look as follows. 202 Accepted location: 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 18 VMware, Inc.

19 Chapter 2 Hello vfabric Data Director: A Simplified RESTful Workflow 2 Make an HTTP POST call to create the organization. POST { "adminid": 1, "name": "AuroraOrg" The response that the system returns might look as follows. 202 Created location: 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 2 Retrieve a list of all organization IDs. GET 3 Assign one of the resource bundles to one of the organizations. POST 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 VMware, Inc. 19

20 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 This call performs an assign action and does not include payload data. The response might look like the following. 202 Accepted location: 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 2 Retrieve the list of organizations and look for the ID of the organization that you want to use. GET 3 Retrieve the network information for the resource pool. Because Data Director does not have the resource pool ID, you access it indirectly. GET 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 { "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", 20 VMware, Inc.

21 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 : What to do next Create a database. Create a Database When you need an empty database for a new application, you can create it with a database resource template. The template is configured to allocate resources to the database. Prerequisites Create an organization. See Create an Organization, on page 18. Create a database group. See Create a Database Group, on page 20. Enable a base DB template. See Enable a Base DB Template, on page 19. Procedure 1 Retrieve information about database groups. GET 2 Retrieve information about the resource template for the organization in which you want to create the database. GET 3 Retrieve information about the base DB template. GET VMware, Inc. 21

22 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 You can now use the information that you collected to create the database. The HTTP POST call includes payload data that might be included as application code in a Python or JavaScript application. 5 Create the database. POST { "dbgroupid": 93, "parametergroupsetting": { "parametergroupid": 9, "name": "Aurora", "dbname": "Aurora", "administratorconfig": { "ownername": "Aurora", "ownerpassword": "Aurora", "resourcesetting": { "resourcetemplateid": 88, "basedbtemplateid":5 The response that the system returns might look as follows. 202 Accepted location : 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. The resource template and backup template used in this example are available by default, so you do not have to create them. POST Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json { "administratorconfig": { "ownername": "Aurora", "ownerpassword": "Aurora", "backupsetting": { "backuptemplateid": 15, "basedbtemplateid": 1, 22 VMware, Inc.

23 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": " ", "description": "ip range", "enabled": true, "endaddress": " ", { "beginaddress": " ", "description": "single ip", "enabled": false, "endaddress": " " ], "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 VMware, Inc. 23

24 VMware vfabric Data Director Programming Guide 24 VMware, Inc.

25 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. This chapter includes the following topics: Ingest a Database, on page 25 Clone a Database, on page 26 Refresh a Cloned Database, on page 27 Reconfigure a Database, on page 27 Add a Database to the Catalog, on page 28 Delete a Database, on page 28 Ingest a Database You can ingest a database to reproduce a production environment and create a one-time (golden) clone. The imported database is a clone of a physical database that exists outside of Data Director. The example 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. The dbname for the ingestion source is ORAC and the IP address is :/nfs. The example uses the default resource template, so you do not have to create one before you make this call. Prerequisites Verify that you have access to the organization and to the database group in which you want to create the database. Procedure u Make an HTTP POST call to ingest the database. POST Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206cGFzc3dvcmQ= Accept : application/json { "basedbtemplateid": 1, "dbname": "ORAC", "dbgroupid": 26, "description": "RestApiExample: ingestion oracle", VMware, Inc. 25

26 VMware vfabric Data Director Programming Guide "extendedcreationconfig": { "ingestexternaldb": { "ingestionsource": { "address": " :/nfs", "catalogstart": "cirrus_11g/bak6_checkpfile/", "controlfilepath":"c_11g/bak6_checkpfile/bak0_1_diff_data/o1_mf_s_ _80l1otww_.bkp", "networkspeedlimitmb": 100, "optionalpfile": "cirrus_11g/bak6_checkpfile/initorac.ora", "refreshpoint": "relativepath": "dperson/bak1_l0" "ingestionstarttime": L, "name": "ORAC", "resourcesetting": { "resourcetemplateid": 21 The response that the system returns might look as follows. content-length : 0 location : Accepted Clone a Database In Data Director, you can clone a database. You have a choice of cloning operations that include full database clone, linked database clone, and schema only clone. You can customize the clone's database settings and backup settings during clone creation. See the vfabric Data Director Administrator and User Guide for a discussion of cloning. The API supports all clone operations that the Data Director UI supports. The example assumes that you have created the target database group and that the database group ID is 26. Procedure u Use an HTTP POST call to create the clone. POST Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json { "clonepoint": { "clonenow": {, "clonetarget": { "clonebothschemaanddata": { "fullclone": true, 26 VMware, Inc.

27 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 : 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. The database or catalog that a database is cloned from is the source of a cloned database. If the source has been deleted, you cannot refresh the cloned database. When you refresh a cloned database, Data Director performs the following processes. Fetches schema and data from the source. Runs a post-clone script on the schema and data. Applies the schema and data generated by the post-clone script to the cloned database. Procedure u Use an HTTTP POST call to refresh a database from the current state of its parent database. POST Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json The response that the system returns might look as follows. 202 Accepted location : Reconfigure a Database You can reconfigure an existing database, for example, by changing the resource settings. You can only reconfigure existing databases. Procedure u Use an HTTP PUT call to reconfigure the database. PUT Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json { "description": "RestApiExample: reconfigure database", "resourcesetting": { "resourceconfig": { "cpureservationmhz": 0, "highavailabilityenabled": false, VMware, Inc. 27

28 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 : Accepted Add a Database to the Catalog You can add an existing Data Director database to the database group catalog, and use the catalog database to create other databases with known characteristics and preloaded data. You cannot directly modify or power on catalog databases. Prerequisites Create a database group. Procedure u Add the database to the catalog with an HTTP POST call. POST Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json { "cloneparam": { "dstdbgid": 26, "fullclone": true, "srcdbid": 28, "description": "RestApiExample: catalog database", "name": "Aurora_catalog" The response that the system returns might look as follows. content-length : 0 location : 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. 28 VMware, Inc.

29 Chapter 3 Database Operations Procedure u Perform an HTTP DELETE call. DELETE Content-type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json The response that the system returns might look as follows. content-length : 0 location : Accepted VMware, Inc. 29

30 VMware vfabric Data Director Programming Guide 30 VMware, Inc.

31 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. See the vfabric Data Director Administrator and User Guide for a a discussion of available backup procedures. The API supports all features that the Data Director UI supports. This chapter includes the following topics: Back Up Data, on page 31 Restore Data, on page 32 Back Up Data You can use the Data Director GUI to create backup templates and schedule regular backups, or you can back up data with the Data Director API. This call creates a snapshot of a database. Procedure u Use an HTTP POST call to back up the database. POST Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json { "createbackup": { "label": "REST API example", "snapshotbackup": true The response that the system returns might look as follows. 202 Accepted location : What to do next When you need the snapshot of the database, you can use the API to retrieve it. VMware, Inc. 31

32 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 Content-Type : application/json Authorization : Basic YWRtaW5AYXVyb3JhLnZtd2FyZS5jb206Y2xvdWRibXM= Accept : application/json The response that the system returns might look as follows. 202 Accepted location : 32 VMware, Inc.

33 Enumeration Types, Status Codes, 5 and Response Code Examples The API includes some String parameters that are enumeration types, and returns status codes. This chapter includes the following topics: Enumeration Types, on page 33 Status Codes, on page 35 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. Please refer to the VMware vfabric Data Director Call Reference for more detailed information when making REST API calls. entitytype Values: SYSTEM, ORGANIZATION, DB_GROUP, DB_SERVER, RESOURCE_TEMPLATE BACKUP_TEMPLATE, RESOURCE_BUNDLE Used in: api/privilege/entitytype status Values: PENDING, RUNNING, REVERTING, SUCCESS, FAILED, CANCELLED, ERROR_WAIT Used in: TaskRead sharelevel/cpusharelevel/memsharelevel Values: HIGH, NORMAL, LOW, CUSTOM Used in: DbgroupRead, ResourcePoolRead priority Values: Automatic, Low, Normal, High Used in: DatabaseCreate/resourceSetting/resourceConfig, DatabaseUpdate/resourceSetting/resourceConfig, ResourceTemplateRead/resourceConfig type Values: Integer, Boolean, String, Real, Enum Used in: All objects VMware, Inc. 33

34 VMware vfabric Data Director Programming Guide action-afterstorage-exhausted Values: Suspend, DeleteOldest Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig alloctype Values: DHCP, IP_POOL Used in: ResourceBundleCreate/networkSetting/ipAllocTypes, ResourceBundleUpdate/networkSetting/ipAllocTypes extendedretentionfrequency Values: OneDay, OneWeek, OneMonth, ThreeMonths, OneYear Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig extendedretentionperiod Values: OneWeek, TwoWeeks, OneMonth, SixMonths, OneYear, Forever Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig snapshotfrequency Values: Never, FourHours, EightHours, TwelveHours, TwentyHours Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig snapshotretentiontype Values: Hour, Copy Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig snapshotretentionperiod Values: FourHours, EightHours, TwelveHours, TwentyFourHours, FortyEightHours Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig externalfrequency Values: Never, TwelveHours, OneDay, OneWeek, OneMonth Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig externalstarttimeex Values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Beginning, Middle, End Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig externalretention Values: OneDay, OneWeek, TwoWeeks, OneMonth, SixMonths, OneYear Used in: DatabaseCreate/backupSetting/backupConfig, DatabaseUpdate/backupSetting/backupConfig, BackupTemplateRead/backupConfig 34 VMware, Inc.

35 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. 202 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a Location header with a Task URI. 204 No Content The request is valid and was completed. The response does not include a body. 400 Bad Request The request body is malformed, incomplete, or otherwise invalid. 401 Unauthorized An authorization header was expected but not found. 403 Forbidden The requesting user does not have adequate privileges to access one or more objects specified in the request. 404 Not Found One or more objects specified in the request could not be found in the specified container. 409 Conflict The object state is not compatible with the requested operation. 500 Internal Server Error The request was received but could not be completed because of an internal error at the server. Response Code Examples 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. Sample response for OrgCreate: Status: 201 Server: Apache-Coyote/1.1 Location: Content-Length: 0 Date: Wed, 07 Mar :40:07 GMT Sample response for OrgRead Status: 200 Server: Apache-Coyote/1.1 Cache-Control: private Expires: Thu, 01 Jan :00:00 UT Content-Type: application/json Transfer-Encoding: chunked Date: Wed, 07 Mar :40:07 GMT {'status':'normal','description': 'Org created by test harness','id': 243,'name':'Test org' VMware, Inc. 35

36 VMware vfabric Data Director Programming Guide Sample response for OrgUpdate: Status: 204 Server: Apache-Coyote/1.1 Cache-Control: private Expires: Thu, 01 Jan :00:00 UTC Date: Wed, 07 Mar :40:07 GMT Sample response for OrgDelete: Status: 202 Server: Apache-Coyote/1.1 Cache-Control: private Expires: Thu, 01 Jan :00:00 UTC Location: Content-Length: 0 Date: Wed, 07 Mar :40:07 GMT 36 VMware, Inc.

37 Index A API call 33 B back up 31 base DB template enabling 15, 16, 19 using with base DBVM 16 base DBVM, converting 15, 16 C catalog database 28 clone database 26 D database backup 31 creating 21 restore 31 database operations 25 DB group, creating 15, 20 DB groups 8 delete database 28 E enumeration types 33 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 S status codes 35 system resource bundle, creating 15 V versions 7 vfabric Data Director Programming Guide 5 W workflow client 10 REST API 10, 15 G golden clone 25 H HTTP status codes 35 I ingest database 25 O obsolete database 28 organization assigning 15 creating 15, 18 resource bundle 19 R reconfigure database 27 refresh clones 27 VMware, Inc. 37

38 VMware vfabric Data Director Programming Guide 38 VMware, Inc.