Set the version of the Tanzu Service Mesh REST API to use for a request in the resource URL.

The URL of a resource in the Tanzu Service Mesh REST API includes the version of the API:

https://{host}/{project}/{apiversion}/{resource}

{apiversion} in the URL specifies a major API version released in a specific stage of the API life cycle and a minor version. {apiversion} can also include a named reference to the API stage (for example, beta).

A major version contains backwards-incompatible and potentially code-breaking changes. New endpoints are released for each major version. If you are upgrading to a major version, make changes to your code to use the new endpoints. A major version uses the format v{major_version}, for example, v1alpha.

A minor version introduces only backwards-compatible features and improvements. The existing endpoints are automatically updated for a minor version. Because a minor version does not cause any breaking changes in your code, you can continue to use older endpoints. Upgrade to a minor version to use the features and improvements in that version. A minor version is indicated in the URL with an integer after a major version number, for example, v1alpha1.

Examples:

https://prod-1.nsxservicemesh.vmware.com/tsm/v1alpha1/global-namespaces

https://prod-1.nsxservicemesh.vmware.com/tsm/v1beta2/clusters

For guidance on using versions released within the different stages of the Tanzu Service Mesh REST API, see the section "API Stages."

API Stages

The Tanzu Service Mesh REST API is transitioning from early stages to more mature stages. As new resource endpoints are added and changes are made to existing resources, new versions of the API are made available.

The life cycle of the Tanzu Service Mesh REST API consists of the following stages. Consider the guidelines for using API versions released in each stage.

  • Alpha (for example, v1alpha1)

    • This is the current version of the API. The sample requests in this guide use an alpha version.

    • Alpha versions are largely untested.

    • The API may change completely with limited notice.

    • Do not use alpha versions in production environments.

    • The API can be modified without a version change. However, if changes are not backward compatible, a new version is released, for example, v1alpha2.

    • Use only for testing and understanding the API.

  • Beta (for example, v1beta1)

    • The code has been tested, and the API works as documented.

    • The support for the features will not change.

    • The API schemas might change between re-releases and a stable version.

    • Migration of the API will not be supported seamlessly and may require a careful migration strategy. The migration will require users to rewrite their configurations and may cause downtime.

    • The API can be modified without a version change. However, if changes not backwards compatible, a new version is released, for example, v1beta2.

    • Do not use beta versions for business-critical applications.

  • Stable (for example, v1)

    • The API is stable and will likely not change for a long time.

    • The API is well tested and documented.

    • The API schemas are expected not to change. If they do, an effective migration strategy will be provided.

    • Backward compatibility is maintained.

    • When stable versions become available, v1 beta and v1 alpha will no longer be supported.