VMware Cloud Foundation API Reference Guide

VMware Cloud Foundation API Reference Guide

1. Overview

VMware Cloud Foundation API Reference Guide

1.1. Version information

Version : 3.8.1-RELEASE

1.2. Contact information

Contact : http://www.vmware.com/

1.3. License information

License : VMware Cloud Foundation
Terms of service : http://www.vmware.com/

1.4. URI scheme

Host : sddc-manager.sfo01.rainpole.local
BasePath : /
Schemes : HTTPS

1.5. Tags

  • Clusters : APIs for managing Clusters

  • Credentials : APIs for managing Credentials

  • Domains : APIs for managing Domains

  • Hosts : APIs for managing Hosts

  • License Keys : APIs for managing License Keys

  • Network Pools : APIs for managing Network Pools

  • Tasks : APIs for managing Tasks

1.6. API Versioning

  • API versioning is at the granularity of each resource.

  • API versioning is similar to URI versioning so that it is explicit, i.e all APIs have the "/<version>/" prefix.

  • The API version is independent of the product version and will evolve independently.

Tip
 Reference APIs using the full path (/v1/hosts) so that any future changes can be localized to a small footprint. When the version is incremented, update the old APIs with new APIs and the corresponding changes.
Note

  • An illustration of versioning is shown in the table below, assuming the product version is incremented from N to N+1, N+2 and so on. The illustration shows how the API version is incremented.

  • The API version is incremented when there are backward incompatible changes.

  • The APIs are deprecated when the version is incremented from N to N+1.
Product Version APIs

Product Version N

  • /v1/hosts

  • /v1/domains

  • /v1/clusters

Product Version N+1

  • /v1/hosts

  • /v1/domains (Deprecated)

  • /v2/domains

  • /v1/clusters

Product Version N+2

  • /v1/hosts (Deprecated)

  • /v2/hosts

  • /v1/domains (Deprecated)

  • /v2/domains

  • /v1/clusters

Product Version N+3

  • /v1/hosts (Deprecated)

  • /v2/hosts (Deprecated)

  • /v3/hosts

  • /v1/domains (Deprecated)

  • /v2/domains

  • /v1/clusters

1.7. Security

  • All APIs are secured and need a username and password for invocation

  • The username and password are sent using Basic Authentication scheme

  • To invoke the APIs, SDDC Manager "admin" and its password is required.

Tip
 For security reasons, you should periodically update the password for this account.

  • To use more secured APIs like Get the Credentials, Update or rotate passwords for a list of resources, Retry a failed credentials task for a given ID, dual authentication is required. A privileged user has to be created in management domain vCenter and associated to group "Sddc_Secured_Access". Along with "admin" account, Privileged user credentials has to be passed in request headers("privileged-username" and "privileged-password") of secured APIs in plain text. Please refer VMware Cloud Foundation Operations and Administration Guide for setting up privileged user.

  • If you write a script that invokes the APIs, the script should either prompt the user to enter the password for the "admin" account or should accept the password as a command line option. TAs a best practice, you should not encode the password for the account in the script code itself.

  • Script should also accept privileged user credentials if the script is invoking any secured APIs defined above.

1.7.1. Changing the "admin" account password

  • SSH in to the SDDC Manager VM, login as "vcf" user.

  • Enter su to switch to the "root" user.

  • Enter the following command:

/opt/vmware/vcf/commonsvcs/scripts/auth/set-basicauth-password.sh admin <password>

  1. For <password>, enter the new password to associate with the admin account.

Password requirements:
* Length: 8-12 characters
* Must include: mix of upper-case and lower-case letters a number a special character such as @ ! # $ % ^ or ?
* Cannot include: * { } [ ] ( ) / \ ' " ` ~ , ; : . < >