Expose supported api-versions for each service

[jongio]

We need to communicate to our customers which service data plane api-versions each library supports, so they can determine if they can use the new SDKs for their given instance of a service. For example, Cloud1 has KeyVault api-version 6.0 deployed, but the minimum supported value is 7.0 by the new SDKs. That customer would therefore need to use the previous SDKs.

These values are currently embedded within each SDK, but not exposed in a clean way to our customers.

The requirements are:

1. The service api-version supported values need to be easily managed by each service and SDK team.
2. The service api-version supported values need to be display in each service README.
3. The service api-version supported values need to be displayed with Docs core and any reference documentation.
4. The service api-version supported values need to be easily integrated into other software, such as the Azure global parity dashboard. Do not embed these values within markdown which will require integrators to parse markdown to retrieve the values. Provide the values in a format that is easily downloadable, such as a data file in the azure-sdk repo.
5. The service api-version supported values need to be surfaced on the https://aka.ms/azsdk/releases package list, so a customer can easily find all of these values without having to go to each repo individually.

[weshaggard]

@johanste @KrzysztofCwalina @JonathanGiles @JeffreyRichter @bterlson Does the architecture board have any recommendations on providing the services versions in a consistent way across languages?

[JeffreyRichter]

Ultimately, this must be done via documentation as customers should know what service API versions are supported for a library version BEFORE the customer downloads that library.

[KrzysztofCwalina]

The ServiceVersion enum in each package has all the supported versions. But, it should also be highlighted in the docs.

[weshaggard]

As best I can tell there isn't any consistency across the languages on this front. As an example for storage blobs I've found:

• .NET exposes BlobClientOptions.ServiceVersions enum that list the versions here
• Java exposes BlobServiceVersion enum that lists the versions here
• Typescript doesn't expose the versions it supports and currently it only supports one version defined here
• Python doesn't expose the versions it supports but does define the list here

In the case of blobs all the libraries support 2019-02-02 and 2019-07-07, except typescript which only supports 2019-07-07.

For another example we see KeyVault Secrets:

• .NET exposes SecretClientOptions.ServiceVersion with V7_0 and V7_1_PREVIEW as the version here defaulting to V7_1_PREVIEW
• Java exposes SecretServiceVersion with V7_0 and V7_1_PREVIEW as the versions here defaulting to v7_1_Preview.
• Typescript doesn't expose but supports 7.0 and 7.1-preview here defaulting to v7.1-preview
• Python exposes ApiVersion with V7_0, V7_1_preview, and V2016_10_01 here defaulting to V7_1_preview

In the kevvault secrets case they all support 2 versions consistently except python supports one older version. It is also interesting that our libraries are supporting preview versions of the service apis.

In my few use cases .NET and Java are consistent in how they expose service versions and they make them public so any consumers can kind of figure out what is supported. However TS and Python don't expose the APIs and how they store them internally isn't consistent enough for any automation to try and extract them. @johanste @bterlson do you guys have any planned updates to the language guidelines to have the supported service versions exposed in some way?

To help with documenting and other tools that might want to consume the supported versions I'm going to add a guideline to our README.md guidance that will define a format for library devs to list out the supported service versions in their package README. That will enable us to get these documented and allow us to easily pull that data into our package index.

[weshaggard]

Looks like I missed a recent Archboard meeting about some of these issues #1043 and looks like @adrianhall updated the general guidelines in #1058. We just haven't implemented those guidelines in all languages and services yet. While this #1058 contains general guidelines I'm curious if there are plans to define the language specific way to expose the supported service versions for Typescript (@bterlson) and Python (@johanste)?

[jongio]

@weshaggard - Python implemented an ApiVersion construct : https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-keys/CHANGELOG.md#420b1-2020-03-10

https://github.com/Azure/azure-sdk-for-python/blob/efb86d404eefa8f792b9384259902f0adfbf9312/sdk/keyvault/azure-keyvault-certificates/azure/keyvault/certificates/_shared/multi_api.py

[weshaggard]

@jongio thanks for the pointer I was mis-interpreting the python code and had a copy/paste error in my link. I've updated my post inline above to fix this.

[JonathanGiles]

One thing I've been considering in Java is to annotate all service methods (i.e. methods that represent calls to the Azure service) with a min / max supported service version, or a list of supported versions. This would give granular information in the published JavaDocs for all service methods about the range of supported service versions. I'm not sure if that has much value or not, or if it is likely to be ignored in favour of an overall value for an entire release of a library.

[weshaggard]

Talking with @Petermarcu about this again recently and this is something we still want to do. I'll try to work with the TypeSpec working group to see about adding these api-versions into the source map we plan to build for the cross-language APIView features.

[github-actions]

Hi @jongio, we deeply appreciate your input into this project. Regrettably, this issue has remained inactive for over 2 years, leading us to the decision to close it. We've implemented this policy to maintain the relevance of our issue queue and facilitate easier navigation for new contributors. If you still believe this topic requires attention, please feel free to create a new issue, referencing this one. Thank you for your understanding and ongoing support.