Update API version policy to handle path params (#24996)

For an API version in a path segment, it is assumed that the client has
replaced the applicable path segment with the API version. In this case,
the pipeline policy is a no-op.

Author: jhendrixMSFT

sdk/azcore/CHANGELOG.md

@@ -1,9 +1,11 @@
 # Release History
 
-## 1.18.3-beta.1 (Unreleased)
+## 1.19.0 (Unreleased)
 
 ### Features Added
 
+* Added `runtime.APIVersionLocationPath` to be set by clients that set the API version in the path.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/azcore/internal/shared/constants.go

@@ -40,5 +40,5 @@ const (
 	Module = "azcore"
 
 	// Version is the semantic version (see http://semver.org) of this module.
-	Version = "v1.18.3-beta.1"
+	Version = "v1.19.0"
 )

sdk/azcore/runtime/policy_api_version.go

@@ -16,9 +16,10 @@ import (
 
 // APIVersionOptions contains options for API versions
 type APIVersionOptions struct {
-	// Location indicates where to set the version on a request, for example in a header or query param
+	// Location indicates where to set the version on a request, for example in a header or query param.
 	Location APIVersionLocation
-	// Name is the name of the header or query parameter, for example "api-version"
+	// Name is the name of the header or query parameter, for example "api-version".
+	// For [APIVersionLocationPath] the value is not used.
 	Name string
 }
 
@@ -30,6 +31,8 @@ const (
 	APIVersionLocationQueryParam = 0
 	// APIVersionLocationHeader indicates a header
 	APIVersionLocationHeader = 1
+	// APIVersionLocationPath indicates a path segment
+	APIVersionLocationPath = 2
 )
 
 // newAPIVersionPolicy constructs an APIVersionPolicy. If version is "", Do will be a no-op. If version
@@ -55,7 +58,10 @@ type apiVersionPolicy struct {
 
 // Do sets the request's API version, if the policy is configured to do so, replacing any prior value.
 func (a *apiVersionPolicy) Do(req *policy.Request) (*http.Response, error) {
-	if a.version != "" {
+	// for API versions in the path, the client is responsible for
+	// setting the correct path segment with the version. so, if the
+	// location is path the policy is effectively a no-op.
+	if a.location != APIVersionLocationPath && a.version != "" {
 		if a.name == "" {
 			// user set ClientOptions.APIVersion but the client ctor didn't set PipelineOptions.APIVersionOptions
 			return nil, errors.New("this client doesn't support overriding its API version")

sdk/azcore/runtime/policy_api_version_test.go

@@ -80,7 +80,10 @@ func TestAPIVersionPolicy(t *testing.T) {
 		// ctor via NewPipeline(). The policy should return an error when the user specifies a version
 		// the policy can't set because the service client didn't identify the header/query param.
 		{version: version, err: true},
-		{location: 2, version: version, err: true},
+		{location: 3, version: version, err: true},
+
+		// for APIVersionLocationPath the policy does nothing
+		{location: APIVersionLocationPath},
 	} {
 		t.Run("no-op", func(t *testing.T) {
 			p := newAPIVersionPolicy(test.version, &APIVersionOptions{Location: test.location, Name: test.name})