VMware Cloud Foundation on Dell EMC VxRail API Reference Guide

1. Overview

1.2. License information

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

1.3. URI scheme

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

1.4. Tags

BackupRestore : APIs for managing Backups and Restore
Bundles : APIs for managing Bundles
CEIP : APIs for managing CEIP status
Certificates : APIs for managing Certificates
Clusters : APIs for managing Clusters
Credentials : APIs for managing Credentials
DepotSettings : APIs for managing Depot Settings
Domains : APIs for managing Domains
Federation : APIs for managing Federation
Hosts : APIs for managing Hosts
License Keys : APIs for managing License Keys
Members : APIs for managing Members of the Federation
Membership Token : APIs for managing Membership Token
NSX-T Clusters : APIs for managing NSX-T Clusters
NsxTEdgeClusters : APIs for managing NSX-T Edge Clusters
Progress : APIs for progress of Federation Tasks
SddcManagers : APIs for managing SDDC Managers
SystemPrechecks : APIs for managing System Prechecks
Tasks : APIs for managing Tasks
Tokens : APIs for managing Access and Refresh Token
Upgradables : APIs for managing Upgradables
Upgrades : APIs for managing Upgrades
Users : APIs for managing Users
VcfServices : APIs for managing VCF Services
VersionAliasesForBundleComponentType : APIs for managing Version Alias Configuration
system : APIs for managing DNS & NTP configuration
vCenters : APIs for managing vCenters
vRSLCM : APIs for managing vRealize Suite Lifecycle Manager

1.5. 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.
API version is independent of the product version and will evolve independently.

Tip

Reference APIs using the full path i.e "/v1/hosts" so that any future changes can be localized to a small scope in the automation code. This ensures that when the API version is incremented, you only need to update the references to the old APIs (which are now marked as deprecated) with the new APIs

Note

An illustration of API versioning is shown in the table below.
The illustration assumes that the product version is incremented from N to N+1, N+2 and so on.
The API version is only incremented when there are backward incompatible changes.
The older version of the APIs are deprecated when the version is incremented.

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

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.6. Security

1.6.1. Overview

Cloud Builder APIs

All APIs are secured and need an username and password for invocation.
The APIs follow the Basic Authentication scheme.
To invoke the APIs, Cloud Builder "admin" account account and its password is required.

SDDC Manager APIs

All APIs are secured and need an access token for invocation.
The APIs follow the Bearer Authentication scheme.
To invoke the Restore APIs, SDDC Manager "admin" and its password is required.
- The username and password are sent using Basic Authentication scheme.

Tip	For security reasons, you should periodically update the password of the SDDC Manager 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, the user should have the appropriate role mapped. Refer Authorization section for more details.

1.6.2. Authentication

An access token and a refresh token can be obtained using the Token API. Refer Create a token pair section
An access token has a validity of 1 hour and a refresh token has a validity of 24 hours.
If the access token has expired, a new access token can be obtained using the refresh token (provided the refresh token has not expired). Refer Refresh an access token section.
If the refresh token has expired, a new pair of access and refresh token can be obtained using the Token API. Refer Create a token pair section.
Refer below for various use cases of API invocation and the HTTP response code :-

API invocation	HTTP Response code
With a valid access token	200
Without an access token	401
With an expired access token	401
With an access token with insufficient privileges	403
With an expired or invalid refresh token	404

1.6.3. Authorization

Every user can either have an ADMIN role or an OPERATOR role. Refer Get the Roles and Add users for information to fetch the Role ID and add users.
To invoke 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, the user MUST have the ADMIN role.

1.6.4. Changing the "admin" account password

Cloud Builder APIs

Note	Changing password of the Cloud Builder "admin" account is not supported.

SDDC Manager APIs

You can follow the below steps to change the password for the "admin" account of the SDDC Manager.

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>

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: * { } [ ] ( ) / \ ' " ` ~ , ; : . < >