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.
VMware vFabric Data Director API 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 1 vFabric Data Director API Programming Guide 5 2 About the Data Director API 7 REST API Versioning 7 Client Workflow Overview 7 Understanding Resources and DB Groups 9 Understanding Call Dependencies 10 Working with Enumeration Types 11 3 Making a Call 13 Data Director REST Requests 13 API REST Response Codes 15 4 Hello vFabric Data Director: a Simplified RESTful Workflow 17 Creating a System Resource Bundle 17 Converting a Base DBVM to a Base DB Template 18 Creating a Resource Bundle 19 Crea
VMware vFabric Data Director API Programming Guide 4 VMware, Inc.
1 vFabric Data Director API Programming Guide 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.
VMware vFabric Data Director API Programming Guide 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.
VMware vFabric Data Director API Programming Guide 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.
Chapter 2 About the Data Director API 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.
VMware vFabric Data Director API Programming Guide 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.
Chapter 2 About the Data Director API 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.
VMware vFabric Data Director API Programming Guide Table 2-1.
3 Making a Call 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.
VMware vFabric Data Director API Programming Guide 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.
Chapter 3 Making a Call 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.
VMware vFabric Data Director API Programming Guide 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.
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.
VMware vFabric Data Director API Programming Guide 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\ /datadirect
Chapter 4 Hello vFabric Data Director: a Simplified RESTful Workflow 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\
VMware vFabric Data Director API Programming Guide 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.
Chapter 4 Hello vFabric Data Director: a Simplified RESTful Workflow 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.
VMware vFabric Data Director API Programming Guide 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": 8
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.
VMware vFabric Data Director API Programming Guide 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.
VMware vFabric Data Director API Programming Guide "enabled": true, "endAddress": "10.37.1.100" }, { "beginAddress": "10.37.1.105", "description": "single ip", "enabled": false, "endAddress": "10.37.1.
Chapter 5 Managing a Database 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": { "c
VMware vFabric Data Director API Programming Guide }, "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.
VMware vFabric Data Director API Programming Guide 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 : appli
VMware vFabric Data Director API Programming Guide 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 YWRtaW5AYXVyb3JhLnZtd2
VMware vFabric Data Director API Programming Guide 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.
VMware vFabric Data Director API Programming Guide 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.
Index B V base DB template enabling 17, 18, 21 using with base DBVM 18 base DBVM, converting 17, 18 versions 7 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 W workflow client 7 REST API 7, 17 X XML compressed responses 13 validation 13 E enumeration types 11 examples, conventions for 13 O organization assigning 17 creating 17, 20 resource bundle 20 R requests, about 13 resource bundle as
VMware vFabric Data Director API Programming Guide 38 VMware, Inc.
