VMware vFabric Data Director API 2.5 Release Notes

Released 6 December 2012

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.


These release notes apply to the 2.5 release of the vFabric Data Director API.

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:

  • New database action refreshFromExternalDb

    Affected URL: POST .../api/database/<dbId>?action= refreshFromExternalDb

  • Modified ingestionSource parameter in database create API's request parameter DatabaseCreate for one-time clone-style ingestion.

    Affected URL: POST .../api/databases

  • New parameters osParameterSetting, osAdminPassword in database create API's request parameter DatabaseCreate.

    • osParameterSetting is for passing parameter of Windows for SQL Server provision
    • osAdminPassword is for setting the operating system password when creating database

    Affected URL: POST .../api/databases

  • New parameter staticIpEnabled in database create API's request parameter DatabaseCreate, database update API's request parameter DatabaseUpdate, database clone API's request parameter CloneCreate, catalog clone API's request parameter CloneCreate

    Affected URLs:

    • database create API, POST .../api/databases
    • database update API, PUT .../api/database/<dbid>
    • database clone API, POST .../api/database/<dbId>/clones
    • catalog clone API, POST .../api/catalog/<catalogId>/clones

  • New parameter status in user read API's response parameter UserRead to retrieve the status of the user account.

    Affected URL: GET .../api/user/<userId>

Resolved Issues

This release of the vFabric Data Director API resolves the following issues:

  • When you use the REST API to create a database with a database name that contains blank spaces (such as “db name”), the creation fails with the task error message, The database name is not valid.

  • The new database creation REST API requires the parameterGroupSetting, but now it will not reject a request without it, and the creation will "succeed". However, this may lead to unpredictable errors with further operation on this database. For example, an update database operation might fail with the task error message, "Update db parameter failed.".

  • For the database refresh REST API, the refreshStartTime call refers to one specific time every day when you want to perform a database refresh. Currently, you have to set the format as "Month/Date/Year HH:MM AM", or "Month/Date/Year HH:MM PM", but the date is ignored by the backend engine. Eventually, it should be changed to the format, "HH:MM AM" or "HH:MM PM".

  • The catalog DB doesn't currently support PITR cloning, so you can't update the catalog DB using the cloningConfig cloneState value "ENABLE". If you try to update the catalog DB using this value, the update operation will fail with Internal Error 500.

Known Issues and Workarounds

No API-specific known issues have been reported for this release. 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.