VMware

VMware vFabric Data Director 2.7 API Release Notes

Released 05 May 2013

This document contains the following information:

About the vFabric Data Director API

The VMware vFabric Data Director API allows you to extend or build a vFabric Data Director client using Representational State Transfer (REST) calls and RESTful programming conventions.

To use the vFabric Data Director API, you must already be familiar with common database terminology, the VMware vFabric Data Director product, VMware Virtual Machine technology, and web technologies such as XML, HTTP, and REST.

Download and install the vFabric Data Director API from the VMware download site.

What’s New in This Release?

This release of the vFabric Data Director API includes the following new features and changes:

Multi-Disk Support for Flexible Storage

  • New item storageAllocs in resource bundle create API’s request parameter ResourceBundleCreate, in update API’s request parameter ResourceBundleUpdate. New item storageInfos in resource bundle read API’s response parameter ResourceBundleRead.
    Affected URLs:
    POST .../api/resourcebundles
    PUT .../api/resourcebundle/<rbId>
    GET .../api/resourcebundle/<rbId>
  • New item storageAllocs in DBGroup create API’s request parameter DbgroupCreate, in update API’s request parameter DbgroupUpdate. New item storageInfos in DB group read API's response parameter DbgroupRead.
    Affected URLs:
    POST .../api/dbgroups
    PUT .../api/dbgroup/<dbgId>
    GET .../api/dbgroup/<dbgId>
  • New item diskMapping in database create API’s request parameter DatabaseCreate, in read API’s response parameter DatabaseRead. New item diskResizeConfig in database update API’s request parameter DatabaseUpdate.
    Affected URLs:
    POST .../api/databases
    PUT .../api/database/<dbgId>
    GET .../api/database/<dbgId>
  • New item diskMapping in database clone API and clone catalog to database API’s request parameter CloneCreate.
    Affected URLs:
    POST .../api/database/<dbId>/clones
     POST .../api/catalog/<catalogId>/clones
  • New parameter diskConfig in base DB template create API's request parameter BaseDbTemplateCreate, in read API’s response parameter BaseDbTemplateRead.
    Affected URLs:
    POST .../api/basedbtemplates
     PUT .../api/basedbtemplate/<templateId>

DRS Group Support

  • New item drsVmGroup in resource bundle create API's request parameter ResourceBundleCreate, in read API’s response parameter ResourceBundleRead.
    Affected URLs:
    POST .../api/resourcebundles
     GET .../api/resourcebundle/<rbId>

Task Read Pagination Support

  • New query parameters startIndex and count for task read APIs.
    Affected URLs:
    GET .../api/tasks
    GET .../api/org/<orgId>/tasks
    GET .../api/dbgroup/<dbgId>/tasks
    GET .../api/database/<dbId>/tasks

Miscellaneous Changes

  • New item hostname in database create API’s request parameter DatabaseCreate, in read response parameter DatabaseRead.
    Affected URLs:
    POST .../api/databases
    GET .../api/database/<dbId>
  • New API GET .../api/resourcebundle/<rbId>/basedbtemplate/<basedbtemplateId> to read base DB template information in assigned resource bundle.
  • New item inResourceBundleInfo in base DB template read API’s response parameter BaseDbTemplateRead.
  • New item connectionStrings in DB read API’s response parameter DatabaseRead.

Deprecated Items

This release includes a number of deprecated items. For backward compatibilities, these items are still supported in this release. The items will eventually become unsupported.
  • dataStorageSize, backupDataStoreRefId and backupStorageSize in SysResourceBundleCreate.
  • dataDataStoreRefId, dataStorageSize, backupDataStoreRefId, backupStorageSize in ResourceBundleCreate.
  • dataDatastore, dataStorageAlloc, backupDatastore, backupStorageAlloc in ResourceBundleRead.
  • dataStorageSize, backupStorageSize in ResourceBundleUpdate.
  • dataStorageAlloc, backupStorageAlloc in DbgroupCreate.
  • dataStorageAllocMb, backupStorageAllocMb in DbgroupRead.
  • dataStorageAlloc, backupStorageAlloc in DbgroupUpdate.
  • storageGb in ResourceTemplateCreate.resourceConfig, ResourceTemplateRead.resourceConfig, ResourceTemplateUpdate.resourceConfig, DatabaseCreate.resourceSetting.resourceConfig, DatabaseRead.resourceSetting.resourceConfig, DatabaseUpdate.resourceSetting.resourceConfig, CloneCreate.resourceSetting.resourceConfig.
  • share, limit in DbgroupCreate.cpuAlloc, DbgroupCreate.memAlloc, DbgroupUpdate.cpuAlloc, DbgroupUpdate.memAlloc.
  • connectionString in DatabaseRead

Resolved Issues

This release of the vFabric Data Director API did not have outstanding known issues. As a result, this release does not resolve any issues.

Known Issues and Workarounds

The vFabric Data Director has following known issues:

  • The default SQL server base database template does not support an auto backup profile. If you specify backupSetting for this template, the REST API ignores it without raising an error.
  • The vFabric Data Director API version 2.7 includes changes that are not usually noticeable to REST API users. The REST client version 2.0 or version 2.5 works with the version 2.7 server. However, when you use old (2.0 or 2.5) resource bundle create and read APIs, a version 2.0 or version 2.5 server responds differently than a version 2.7 server.
    As a result, you see the following behavior for resource bundle dataStorageSize and backupStorageSize:
    • Using dataStorageSize and backupStorageSize on 2.7 client -- Not available.
    • Using dataStorageSize and backupStorageSize on 2.0 or 2.5 client with 2.0 or 2.5 server target -- Accurate results.
    • Using dataStorageSize and backupStorageSize on 2.0 or 2.5 client against 2.7 server target -- Misleading results.
    For example, assume you create a resource bundle with a 2.0 or 2.5 client and use dataStorageSize 100 and backupStorageSize 50. When you perform a resource bundle read operation against a 2.7 server, the server returns dataStorageSize 150 and backupStorageSize 150 because data storage and backup storage share the same datastore with version 2.0 and version 2.5.
    As a result, you should update both data storage and backup storage if you update resource bundle storage allocation sizes against a 2.7 server with a version 2.0 or version 2.5 client.
  • The system resource bundle update API PUT .../api/sysresourcebundle is deprecated in version 2.7 and included only for backward compatibility. If you use SysResourceBundleUpdate with the dataStorageSize parameter, the call has no effect.

See the Data Director release notes for a list of general known issues.

Important Notes

The following notes explain some special cases for using the API.

  • You can use the DatabaseCreate API with a custom db parameter group. If you do, pay careful attention to the restrictions of each parameter entity. Restrictions are described in the parameter group template of the corresponding base DB template. For example, the maximum value for vPostgres wal-buffers in overridenDbConfEntity is 16. If you set this value larger than 16, the DatabaseCreate operation fails.

  • You can use the DatabaseCreate API (POST api/databases) to import an existing database virtual machine from one vFabric Data Director server into another running vFabric Data Director server. In this scenario, you can fill in the vmRefId field with the database virtual machine reference id queried from the Data Director UI.