VMware vCloud Suite SDK for REST 6.0 Release Notes

Released 12 MAR 2015

 

This document contains the following sections:

Overview

This SDK documents the REST APIs to access new features introduced in vSphere 6.0 and existing features that did not have a public API prior to the vSphere 6.0 release. The vCloud Suite SDK for REST also contains samples to demonstrate how to use the new APIs.

The version 6.0 SDK enables programmatic access to the following services:

  • Session management
  • Tagging
  • Content Library

Note:  Single Sign-On authentication is available through the VMware vCenter Single Sign On API and the vSphere API. Service discovery is available through the Lookup Service API. This feature can be accessed using the SOAP API mechanism shown in the SDK samples.

Distribution Kit

When you extract the contents of the vCloud Suite SDK for REST distribution kit, the vCloud Suite client SDK is placed in the VMware-vCloud-Suite-SDK-REST-6.0.0 sub-directory:

VMware-vCloud-Suite-SDK-REST-6.0.0-build-num
    VMware-vCloud-Suite-SDK-REST-6.0.0
        client
        docs
        provider (just contains the REST documenation generator)
        open_source_license.txt
        SDK-EULA.txt
        vCloud-Suite-SDK-REST-README.html

You can download the vCloud Suite SDK for REST distribution kit from the VMware Developer Center.

Known Issues

The following issues were discovered during testing.

  • Internal Server Error if Tagging Description Field is Empty

    The Tag Category Description field is optional in the vSphere Web Services API, but it is mandatory in the vCloud Suite SDK. Therefore, if the description field is empty, the vCloud Suite SDK can return an internal server error that states, "the ‘description’ field of the Category model is empty".

    Workaround:

    When creating tags, do not leave the description field empty. If you do not have any description, you may add a whitespace character (i.e. space).

  • Unauthenticated exception following long-running operation

    After an API client completes a long-running operation, such as an upload to the content library, the next operation might fail with an "Unauthenticated exception" message. This happens if the long running operation did not complete within the lifetime of the authentication session.

    Workarounds:

  • Keep the session alive by issuing short operations on another thread until the long running operation completes.
  • Increase the session length using the VMware vSphere Web Client. Select Administration > System Configuration > Services > vAPI Endpoint > Manage > General, and increase the value for the Maximum session idle time.
  • The vAPI REST layer deserializes all DataValue structure fields to Strings
    The Opaque type maps to the DataValue type which is defined in the vAPI runtime specification and can represent any value in the new Virtualization Management Object Definition Language (VMODL2). Because the actual type of data structure which is declared as Opaque is not visible to the vAPI REST layer, the DataValue structures are deserialized to Strings.

    Workaround: None.

  • Enabling certificate validation

    The samples in the vCloud Suite SDK for REST do not enable certificate validation for service endpoints by default. To enable certificate validation, modify the code that sets request options. Where the flag rejectUnauthorized is set to false in the samples, set the value to true instead.

    If the service endpoint uses an untrusted certificate, you have two ways to use it in the client:

    • Download the certificate authority's root certificate, using a Web browser connected to the service endpoint, and import it into your client machine certificate store.
    • Modify the sample code to specify a certificate file in the request options.

    The following code extract shows the second way:

    function makeAuthRequestOptions(ssoConnectionInfo, requestXml) {
       return {
          host: ssoConnectionInfo.host,
          path: ssoConnectionInfo.path || '/sts/STSService/vsphere.local',
          port: ssoConnectionInfo.port || 443,
          method: 'POST',
          rejectUnauthorized: true, // was: false to ignore server SSL validation. 
          ca: fs.readFileSync('/path/to/downloaded/root.cer'), // VMCA root certificate from PSC
          requestCert: true,
          agent: false,
          headers: {
             'Content-type': 'text/xml; charset="UTF-8"',
             'Content-length': requestXml.length,
             'User-Agent': 'VMware/jsSample',
             'Connection': 'keep-alive',
             'SOAPAction': "http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue"
          }
       }
    }
    

    Note: When you test with certificate validation enabled, use only host names in the service endpoint URL. Certificates will not validate against endpoints constructed with IP addresses.