[Storage] Support multiple service versions

[jeremymeng]

Current storage libraries only support one version. .NET allows passing service version via client pipeline options. We should consider support similar?

/cc @bterlson

[bterlson]

serviceVersion in pipeline options seems good to me. Thoughts?

[jeremymeng]

Related disucssion Azure/azure-sdk#1043 and Azure/azure-sdk#1198

[jiacfan]

My consideration here is SDK functions are closely binding to specific Min service version. So customer could face case that bunch of APIs are not working, and they even have no idea what's the set should work. So exposing service version customization might be risky.

As another option, user can choose to use right version of storage SDK with specific service version, where all APIs are by design work.

At same time, for advanced user they can choose to customize service version with pipeline option.

[XiaoningLiu]

Techinically it's easy to add serviceVersion to storage client pipeline options. But we cannot guarantee all functionalities will work as expected when customer set to a old or newer serviceVersion.

Option 1: Customer customize and override serviceVersion via customized pipeline policy. Under their own risk
Option 2: Provide new serviceVersion client pipeline option, no validation, customer use that option under their own risk
Option 3: Provide new serviceVersion client pipeline option, limit to a subset of supported API versions (can do backward compatibility check, difficult to do forward compatibility check)
Option 4: Provide new serviceVersion client pipeline option. We do API level check. Each API defines compatible API version ranges.
Option 5: Create a new @azure/storage-blob-multi-version package, which internally depends on history versions of @azure/storage-blob (some techinical blockers need to handle from npm). Create clients according to different serviceAPI version.

[tg-msft]

.NET currently supports V2019_02_02, V2019_07_07, and V2019_12_12.

[XiaoningLiu]

@tg-msft will .NET guarantee each version from V2019_02_02, V2019_07_07, and V2019_12_12 will work properly for each API and parameters?

[tg-msft]

Yes, we run our tests across multiple versions of the API to ensure everything continues working. Newer APIs will obviously only work with later service versions, but an error is thrown if that happens. Our guidance to customers is "application developers should always float on the latest service version (which happens by default if you don't explicitly specify a version) and library developers should lock to a specific service version they tested against."

[jeremymeng]

1. Currently for the single version enum in swagger json, generated code from our TS codegen don't accept api versions (except in file-share swagger json where ApiVersionParameter parameter is not specified). It might just work if we add more versions (via transformation), or remove the parameter.
2. Testing multiple versions. Probably add a [V2019_02_02, V2019_07_07, and V2019_12_12].forEach() loop for every test and pass the version to client constructor, after 1) is resolved.

[XiaoningLiu]

Some APIs or some parameters of APIs are only avaiable on latest version. I'm thinking how to handle these cases when customers use these latest version only APIs or parameters.

Sometimes, existing APIs will have breaking change in latest version. In this case, we need to matain multi versions of same API implementation. But swagger is linked to latest swagger.

[jeremymeng]

Right, unless we use multiple generated clients for multiple versions of swagger. However that would have great impact on the bundle size for browsers.

[jeremymeng]

I'm thinking how to handle these cases when customers use these latest version only APIs or parameters.

Does the service return an error in this case?

Sometimes, existing APIs will have breaking change in latest version. In this case, we need to matain multi versions of same API implementation.

@tg-msft How did .NET solve this problem without multiple backends?

[bterlson]

Just chiming in to say that I suppose an apiVersion PipelineOptions with methods which throw when they know they can't work with the selected API version. Agree with Jeremy that we can't do multiple back-ends because the package will be too fat.

[jeremymeng]

For testing:

• See the document on how to update tests to enable multi-version testing
• For a real example, also check out this Key Vault Keys PR [KeyVault] - Add multi-version tests for KeyVault Keys #14587 to enable multi version and run matrix in our weekly pipeline

[github-actions]

Hi @jeremymeng, 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.