VMware Cloud Foundation on Dell EMC VxRail API Reference Guide
1. Overview
VMware Cloud Foundation on Dell EMC VxRail API Reference Guide
1.2. License information
License : VMware Cloud Foundation
Terms of service : http://www.vmware.com/
1.3. URI scheme
Host : sfo-vcf01.rainpole.io
BasePath : /
Schemes : HTTPS
1.4. Tags
-
AVNs : APIs for managing Solutions Networking (Application Virtual Networks)
-
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
-
FIPS mode details : APIs for getting FIPS mode details
-
Federation : APIs for managing Federation
-
Hosts : APIs for managing Hosts
-
License Keys : APIs for managing License Keys
-
Manifests : APIs for managing LCM Manifests
-
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
-
Releases : APIs for managing Releases
-
SDDC : APIs for managing SDDC
-
SOS : APIs for managing SOS
-
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
-
Trusted Certificates : APIs for managing Trusted Certificates
-
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
-
VxRailManagers : APIs for managing VxRailManagers
-
WSA : APIs for managing Workspace ONE Access for vRealize
-
system : APIs for managing DNS & NTP configuration
-
vCenters : APIs for managing vCenters
-
vRA : APIs for managing vRealize Automation
-
vRLI : APIs for managing vRealize Log Insight
-
vROPs : APIs for managing vRealize Operations
-
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
|
|
| Product Version | APIs |
|---|---|
Product Version N |
|
Product Version N+1 |
|
Product Version N+2 |
|
Product Version N+3 |
|
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.
|
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. |
1.7. URL Encoding
While invoking any API, make sure to encode the URL twice using UTF-8 encoding scheme if the URL contains any non-ASCII character.
Example:
Character # is first encoded to %23, which is again encoded to %2523.
1.8. API Changelog
|
Note
|
Legacy APIs, that predated the launch of public APIs, will no longer be accessible. These legacy APIs use Basic Authentication mechanism which is not considered as an enterprise grade security mechanism and hence not recommended. All current public APIs use Token based authentication mechanism. |
| Verb | Path | Parameter/Property |
|---|---|---|
GET |
(New) /v1/system/health-summary |
Not Applicable |
GET |
(New) /v1/system/health-summary/{id} |
Not Applicable |
GET |
(New) /v1/system/health-summary/{id}/data |
Not Applicable |
POST |
(New) /v1/system/health-summary |
Not Applicable |
GET |
(New) /v1/system/support-bundles |
Not Applicable |
GET |
(New) /v1/system/support-bundles/{id} |
Not Applicable |
GET |
(New) /v1/system/support-bundles/{id}/data |
Not Applicable |
POST |
(New) /v1/system/support-bundles |
Not Applicable |
GET |
/v1/clusters |
|
GET |
/v1/clusters/{id} |
|
POST |
/v1/clusters |
|
PATCH |
/v1/clusters/{id} |
|
POST |
/v1/clusters/validations |
|
POST |
/v1/clusters/{id}/validations |
|
POST |
/v1/domains |
|
PATCH |
/v1/domains/{id} |
|
POST |
/v1/domains/validations |
|
POST |
/v1/domains/{domainId}/clusters/{clusterName}/queries |
|
GET |
/v1/domains/{domainId}/clusters/{clusterName}/queries/{queryId} |
|
POST |
/v1/domains/{domainId}/clusters/queries |
|
GET |
/v1/domains/{domainId}/clusters/queries/{queryId} |
|