VMware Cloud Foundation on Dell EMC VxRail API Reference Guide

VMware Cloud Foundation on Dell EMC VxRail API Reference Guide

1. Overview

VMware Cloud Foundation on Dell EMC VxRail is jointly engineered by VMware and Dell EMC, providing the best-in-class serviceability and lifecycle management capabilities for customers looking to automate the deployment and management of the full VMware Software Defined Datacenter (SDDC) stack on Dell EMC VxRail. Full-stack integration with Cloud Foundation on VxRail means both HCI infrastructure layer and VMware cloud software stack lifecycle are managed as one complete automated turnkey hybrid cloud experience, greatly reducing risk and increasing the IT operational efficiency. This API reference guide covers APIs of both Cloud Builder and SDDC Manager applicable for VCF on Dell EMC VxRail.

1.1. Version information

Version : 4.4.0-vcf4400RELEASE

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 : sfo-vcf01.rainpole.io
BasePath : /
Schemes : HTTPS

1.5. 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

  • Hosts : APIs for managing Hosts

  • License Keys : APIs for managing License Keys

  • Manifests : APIs for managing LCM Manifests

  • NSX-T Clusters : APIs for managing NSX-T Clusters

  • NsxTEdgeClusters : APIs for managing NSX-T Edge Clusters

  • Releases : APIs for managing Releases

  • SDDC : APIs for managing SDDC. The /v1/sddcs APIs are available only on the Cloud Builder appliance.

  • SOS : APIs for managing SOS

  • SddcManagers : APIs for managing SDDC Managers

  • SystemPrechecks : APIs for managing System Prechecks

  • Target upgrade version : APIs for managing domains target upgrade versions

  • 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.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.

  • 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.
Note
 The illustration assumes that the product version is incremented from N to N+1, N+2 and so on.
Note
 The API version is only incremented when there are backward incompatible changes.
Note
 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 (New)

  • /v1/clusters

Product Version N+2

  • /v1/hosts (Deprecated)

  • /v2/hosts (New)

  • /v1/domains (Deprecated)

  • /v2/domains

  • /v1/clusters

Product Version N+3

  • /v1/hosts (Deprecated)

  • /v2/hosts (Deprecated)

  • /v3/hosts (New)

  • /v1/domains (Deprecated)

  • /v2/domains

  • /v1/clusters

1.7. Security

1.7.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

1.7.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.7.3. Authorization

1.7.4. Changing the "admin" account password

Cloud Builder APIs

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

1.8. 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.9. 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/domains/{id}/tags

Not Applicable

GET

(New) /v1/domains/{id}/tags/tag-manager

Not Applicable

POST

(New) /v1/domains/{id}/tags/attach

Not Applicable

POST

(New) /v1/domains/{id}/tags/detach

Not Applicable

GET

(New) /v1/domains/{id}/tags/attachable-tags

Not Applicable

PUT

(New) /v1/domainTargetVersion

Not Applicable

GET

(New) /v1/domainTargetVersion

Not Applicable

GET

(New) /v1/clusters/{id}/tags

Not Applicable

GET

(New) /v1/clusters/{id}/tags/tag-manager

Not Applicable

POST

(New) /v1/clusters/{id}/tags/attach

Not Applicable

POST

(New) /v1/clusters/{id}/tags/detach

Not Applicable

GET

(New) /v1/clusters/{id}/tags/attachable-tags

Not Applicable

GET

(New) /v1/hosts/{id}/tags

Not Applicable

GET

(New) /v1/hosts/{id}/tags/tag-manager

Not Applicable

POST

(New) /v1/hosts/{id}/tags/attach

Not Applicable

POST

(New) /v1/hosts/{id}/tags/detach

Not Applicable

GET

(New) /v1/hosts/{id}/tags/attachable-tags

Not Applicable

PUT

(New) /v1/vrslcm

Not Applicable

PUT

(New) /v1/vrslcms/{id}

Not Applicable

GET

(New) /v1/bundles/domains/{id}

Not Applicable

PUT

(Not Supported) /v1/sddc-federation

Not Applicable

GET

(Not Supported) /v1/sddc-federation

Not Applicable

DELETE

(Not Supported) /v1/sddc-federation

Not Applicable

POST

(Not Supported) /v1/sddc-federation/members

Not Applicable

GET

(Not Supported) /v1/sddc-federation/members

Not Applicable

DELETE

(Not Supported) /v1/sddc-federation/members/{memberId}

Not Applicable

POST

(Not Supported) /v1/sddc-federation/membership-tokens

Not Applicable

GET

(Not Supported) /v1/sddc-federation/tasks/{taskId}

Not Applicable

GET

/v1/releases

  • (New QueryParam) getFutureReleases

  • (New QueryParam) applicableForVxRailVersion

  • (New QueryParam) vxRailVersionEq

  • (New QueryParam) vxRailVersionGt

  • (New) PageOfRelease.Release.notApplicableReason

  • (New) PageOfRelease.Release.sku

  • (New) PageOfRelease.Release.isApplicable

POST

/v1/manifests

  • (New) Manifest.Release.notApplicableReason

  • (New) Manifest.Release.sku

  • (New) Manifest.Release.isApplicable

GET

/v1/manifests

  • (New) Manifest.Release.notApplicableReason

  • (New) Manifest.Release.sku

  • (New) Manifest.Release.isApplicable

POST

/v1/domains

  • (New) DomainCreationSpec.ComputeSpec.ClusterSpec.DatastoreSpec.vsanRemoteDatastoreClusterSpec

  • (New) DomainCreationSpec.NsxTSpec.nsxManagerAuditPassword

  • (New) Task.localizableDescriptionPack

  • (Deprecated) DomainCreationSpec.ComputeSpec.ClusterSpec.skipThumbprintValidation

GET

/v1/domains

  • (New) PageOfDomain.Domain.tags

POST

/v1/domains/validations

  • (New) DomainCreationSpec.ComputeSpec.ClusterSpec.DatastoreSpec.vsanRemoteDatastoreClusterSpec

  • (New) DomainCreationSpec.NsxTSpec.nsxManagerAuditPassword

  • (Deprecated) DomainCreationSpec.ComputeSpec.ClusterSpec.skipThumbprintValidation

PATCH

/v1/domains/{id}

  • (New) DomainUpdateSpec.ClusterSpec.DatastoreSpec.vsanRemoteDatastoreClusterSpec

  • (New) DomainUpdateSpec.NsxTSpec.nsxManagerAuditPassword

  • (New) Task.localizableDescriptionPack

  • (Deprecated) DomainUpdateSpec.ClusterSpec.skipThumbprintValidation

GET

/v1/domains/{id}

  • (New) Domain.tags

DELETE

/v1/domains/{id}

  • (New) Task.localizableDescriptionPack

POST

/v1/domains/{id}/validations

  • (New) DomainUpdateSpec.ClusterSpec.DatastoreSpec.vsanRemoteDatastoreClusterSpec

  • (New) DomainUpdateSpec.NsxTSpec.nsxManagerAuditPassword

  • (Deprecated) DomainUpdateSpec.ClusterSpec.skipThumbprintValidation

POST

/v1/clusters

  • (New) ClusterCreationSpec.ComputeSpec.ClusterSpec.DatastoreSpec.vsanRemoteDatastoreClusterSpec

  • (New) Task.localizableDescriptionPack

  • (Deprecated) ClusterCreationSpec.ComputeSpec.ClusterSpec.skipThumbprintValidation

GET

/v1/clusters

  • (New) PageOfCluster.Cluster.tags

POST

/v1/clusters/validations

  • (New) ClusterCreationSpec.ComputeSpec.ClusterSpec.DatastoreSpec.vsanRemoteDatastoreClusterSpec

  • (Deprecated) ClusterCreationSpec.ComputeSpec.ClusterSpec.skipThumbprintValidation

PATCH

/v1/clusters/{id}

  • (New) ClusterUpdateSpec.name

  • (New) Task.localizableDescriptionPack

  • (Deprecated) ClusterUpdateSpec.ClusterExpansionSpec.skipThumbprintValidation

GET

/v1/clusters/{id}

  • (New) Cluster.tags

DELETE

/v1/clusters/{id}

  • (New) Task.localizableDescriptionPack

POST

/v1/clusters/{id}/validations

  • (New) ClusterUpdateSpec.name

  • (Deprecated) ClusterUpdateSpec.ClusterExpansionSpec.skipThumbprintValidation

POST

/v1/domains/{domainId}/clusters/queries

  • (New) ClusterQueryResponse.PageOfCluster.Cluster.tags

  • (New) ClusterQueryResponse.QueryInfo.queryId

GET

/v1/domains/{domainId}/clusters/queries/{queryId}

  • (New) ClusterQueryResponse.PageOfCluster.Cluster.tags

  • (New) ClusterQueryResponse.QueryInfo.queryId

POST

/v1/domains/{domainId}/clusters/{clusterName}/queries

  • (New) ClusterQueryResponse.PageOfCluster.Cluster.tags

  • (New) ClusterQueryResponse.QueryInfo.queryId

GET

/v1/domains/{domainId}/clusters/{clusterName}/queries/{queryId}

  • (New) ClusterQueryResponse.PageOfCluster.Cluster.tags

  • (New) ClusterQueryResponse.QueryInfo.queryId

POST

/v1/hosts

  • (New) Task.localizableDescriptionPack

GET

/v1/hosts

  • (New) PageOfHost.Host.tags

DELETE

/v1/hosts

  • (New) Task.localizableDescriptionPack

GET

/v1/hosts/{id}

  • (New) Host.tags

POST

/v1/clusters/{id}/hosts/queries

  • (New) HostQueryResponse.PageOfHost.Host.tags

  • (New) HostQueryResponse.QueryInfo.queryId

GET

/v1/clusters/{clusterId}/hosts/queries/{queryId}

  • (New) HostQueryResponse.PageOfHost.Host.tags

  • (New) HostQueryResponse.QueryInfo.queryId

POST

/v1/hosts/queries

  • (New) HostQueryResponse.PageOfHost.Host.tags

  • (New) HostQueryResponse.QueryInfo.queryId

GET

/v1/hosts/queries/{id}

  • (New) HostQueryResponse.PageOfHost.Host.tags

  • (New) HostQueryResponse.QueryInfo.queryId

POST

/v1/nsxt-clusters/queries

  • (New) NsxTQueryResponse.QueryInfo.queryId

GET

/v1/nsxt-clusters/queries/{id}

  • (New) NsxTQueryResponse.QueryInfo.queryId

GET

/v1/tasks

  • (New) PageOfTask.Task.localizableDescriptionPack

GET

/v1/tasks/{id}

  • (New) Task.localizableDescriptionPack

POST

/v1/avns

  • (New) Task.localizableDescriptionPack

POST

/v1/restores/tasks

  • (New) Task.localizableDescriptionPack

GET

/v1/restores/tasks/{id}

  • (New) Task.localizableDescriptionPack

PUT

/v1/system/backup-configuration

  • (New) Task.localizableDescriptionPack

PATCH

/v1/system/backup-configuration

  • (New) Task.localizableDescriptionPack

PUT

/v1/domains/{domainName}/csrs

  • (New) Task.localizableDescriptionPack

PUT

/v1/domains/{domainName}/certificates

  • (New) Task.localizableDescriptionPack

PATCH

/v1/domains/{domainName}/certificates

  • (New) Task.localizableDescriptionPack

PATCH

/v1/credentials

  • (New) Task.localizableDescriptionPack

PATCH

/v1/credentials/tasks/{id}

  • (New) Task.localizableDescriptionPack

DELETE

/v1/credentials/tasks/{id}

  • (New) Task.localizableDescriptionPack

POST

/v1/edge-clusters

  • (New) Task.localizableDescriptionPack

PATCH

/v1/edge-clusters/{id}

  • (New) Task.localizableDescriptionPack

POST

/v1/personalities

  • (New) Task.localizableDescriptionPack

PATCH

/v1/system/ceip

  • (New) Task.localizableDescriptionPack

PUT

/v1/system/dns-configuration

  • (New) Task.localizableDescriptionPack

PUT

/v1/system/ntp-configuration

  • (New) Task.localizableDescriptionPack

POST

/v1/system/prechecks

  • (New) Task.localizableDescriptionPack

GET

/v1/system/prechecks/tasks/{id}

  • (New) Task.localizableDescriptionPack

POST

/v1/upgrades

  • (New) Task.localizableDescriptionPack

PATCH

/v1/upgrades/{upgradeId}

  • (New) Task.localizableDescriptionPack

POST

/v1/upgrades/{upgradeId}/prechecks

  • (New) Task.localizableDescriptionPack

GET

/v1/upgrades/{upgradeId}/prechecks/{precheckId}

  • (New) Task.localizableDescriptionPack

PUT

/v1/vrli/domains

  • (New) Task.localizableDescriptionPack

PUT

/v1/vrops/domains

  • (New) Task.localizableDescriptionPack

POST

/v1/vrslcms

  • (New) Task.localizableDescriptionPack

DELETE

/v1/vrslcm

  • (New) Task.localizableDescriptionPack