Add API Management Version Sets by darrelmiller · Pull Request #2483 · Azure/azure-rest-api-specs

darrelmiller · 2018-02-13T03:30:11Z

This checklist is used to make sure that common issues in a pull request are addressed. This will expedite the process of getting your pull request merged and avoid extra work on your part to fix issues discovered during the review process.

PR information

The title of the PR is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For information on cleaning up the commits in your pull request, see this page.
Except for special cases involving multiple contributors, the PR is started from a fork of the main repository, not a branch.
If applicable, the PR references the bug/issue that it fixes.
Swagger files are correctly named (e.g. the api-version in the path should match the api-version in the spec).

Quality of Swagger

I have read the contribution guidelines.
My spec meets the review criteria:
- The spec conforms to the Swagger 2.0 specification.
- The spec follows the guidelines described in the Swagger checklist document.
- Validation tools were run on swagger spec(s) and have all been fixed in this PR.

AutorestCI · 2018-02-13T03:30:41Z

Automation for azure-sdk-for-python

Nothing to generate for azure-sdk-for-python

AutorestCI · 2018-02-13T03:33:05Z

Automation for azure-sdk-for-go

Encountered a Subprocess error: (azure-sdk-for-go)

Command: ['/usr/local/bin/autorest', '/tmp/tmp3qny2epj/rest/specification/apimanagement/resource-manager/readme.md', '--go', '--go-sdk-folder=/tmp/tmp3qny2epj/sdk', '--multiapi', '--package-version=latest', '--use=@microsoft.azure/autorest.go@~2.1.87', "--user-agent='Azure-SDK-For-Go/latest services'", '--verbose']
Finished with return code 1
and output:

AutoRest code generation utility [version: 2.0.4251; node: v7.10.1]
(C) 2018 Microsoft Corporation.
https://aka.ms/autorest
   Loading AutoRest core      '/tmp/.autorest/@microsoft.azure_autorest-core@2.0.4251/node_modules/@microsoft.azure/autorest-core/dist' (2.0.4251)
FATAL: AutoRest exited unexpectedly after launching autorest-core module @microsoft.azure/autorest-core from /tmp/.autorest/@microsoft.azure_autorest-core@2.0.4251
   Loading AutoRest extension '@microsoft.azure/autorest.go' (~2.1.87->2.1.87)
   Loading AutoRest extension '@microsoft.azure/autorest.modeler' (2.3.38->2.3.38)
Processing batch task - {"tag":"package-2017-03"} .
FATAL: System.InvalidOperationException: method RegionsClient.ListByService contains a null nextLinkName so it shouldn't be treated as a pageable operation
   at AutoRest.Go.Model.PageTypeGo..ctor(MethodGo method) in C:\Users\ci\AppData\Local\Temp\PUBLISHwf52p\100_20180220T231516\autorest.go\src\Model\PageTypeGo.cs:line 41
   at AutoRest.Go.Model.CodeModelGo.CreatePageableTypeForMethod(MethodGo method) in C:\Users\ci\AppData\Local\Temp\PUBLISHwf52p\100_20180220T231516\autorest.go\src\Model\CodeModelGo.cs:line 342
   at AutoRest.Go.TransformerGo.TransformMethods(CodeModelGo cmg) in C:\Users\ci\AppData\Local\Temp\PUBLISHwf52p\100_20180220T231516\autorest.go\src\TransformerGo.cs:line 288
   at AutoRest.Go.TransformerGo.TransformCodeModel(CodeModel cm) in C:\Users\ci\AppData\Local\Temp\PUBLISHwf52p\100_20180220T231516\autorest.go\src\TransformerGo.cs:line 25
   at AutoRest.Go.Program.<ProcessInternal>d__3.MoveNext() in C:\Users\ci\AppData\Local\Temp\PUBLISHwf52p\100_20180220T231516\autorest.go\src\Program.cs:line 100
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at NewPlugin.<Process>d__15.MoveNext()
FATAL: go/generate - FAILED
FATAL: Error: Plugin go reported failure.
Process() cancelled due to exception : Plugin go reported failure.
Failure during batch task - {"tag":"package-2017-03"} -- Error: Plugin go reported failure..
  Error: Plugin go reported failure.

anuchandy

Please take a look at the model and linter errors

https://travis-ci.org/Azure/azure-rest-api-specs/jobs/340790418

https://travis-ci.org/Azure/azure-rest-api-specs/jobs/340790417

Also it seems swagger is missing definition for userCollection model

azuresdkciprbot · 2018-02-13T13:55:51Z

Hi There,

I am the AutoRest Linter Azure bot. I am here to help. My task is to analyze the situation from the AutoRest linter perspective. Please review the below analysis result:

File: specification/apimanagement/resource-manager/readme.md
Before the PR: Warning(s): 0 Error(s): 0
After the PR: Warning(s): 0 Error(s): 0

AutoRest Linter Guidelines | AutoRest Linter Issues | Send feedback

Thanks for your co-operation.

azuresdkciprbot · 2018-02-14T00:42:06Z

Hi There,

I am the AutoRest Linter Azure bot. I am here to help. My task is to analyze the situation from the AutoRest linter perspective. Please review the below analysis result:

File: specification/apimanagement/resource-manager/readme.md
Before the PR: Warning(s): 0 Error(s): 0
After the PR: Warning(s): 0 Error(s): 0

AutoRest Linter Guidelines | AutoRest Linter Issues | Send feedback

Thanks for your co-operation.

darrelmiller · 2018-02-14T00:45:25Z

Hey! @anuchandy I believe I have resolved all the issues with this PR. Thanks!

anuchandy · 2018-02-14T18:25:27Z

          "apiVersionSet" : {
            "description": "Version set details",
-            "$ref" : "#/definitions/ApiVersionSetContract"
+            "$ref" : "./apimversionsets.json#/definitions/ApiVersionSetContractProperties"


Note that changing the type of the property apiVersionSet in this model is breaking change.

If we take the diff of ApiVersionSetContract (old type) and ApiVersionSetContractProperties (new type), it looks like the read-only properties id, name and type won't be available for consumer any more.

Changing the type is a SDK breaking change. This requires major SDK version upgrade.

Removing properties in the response of a stable api call (without bumping api version) is service side breaking change, which requires ARM approval.

@anuchandy This isn't breaking a change to the current API, this is fixing an incorrect description. Customer's who attempt to update those fields in the GA release will not be able to.

In the preview release of this API, the customers could create ApiVersionSet directly when creating the API, but it was decided that the ARM guidelines prevented this from being allowed. Therefore we had to remove this functionality for our customers in our GA release. The change to make the fields read-only was missed when doing the update. Our customers are now waiting for the documentation to be updated so they can use the new ARM compliant way of creating these things in a two step process.

If you could unblock this PR so that we can get that documentation to the customer, it would be most appreciated.

/cc @ravbhatnagar

@darrelmiller -
One question, is it the case that service never used to return id, name and type hence swagger was wrong and we are fixing that issue in this PR?

Let me also explain the reason I am thinking this as SDK breaking change. All below SDK issues can be addressed by bumping up SDK version.

The ApiRevisionInfoContract in the current SDK

class ApiRevisionInfoContract { .... public ApiVersionSetContract apiVersionSet {get; set;} }

The ApiRevisionInfoContract in the new SDK (based on this PR)

class ApiRevisionInfoContract { .... public ApiVersionSetContractProperties apiVersionSet {get; set;} }

application code using current sdk

ApiRevisionInfoContract revisionContract = ...; ApiVersionSetContract c = revisionContract.apiVersionSet;

application code using new sdk (based on this PR) [broken]

ApiRevisionInfoContract revisionContract = ...; ApiVersionSetContract c = revisionContract.apiVersionSet; // Compiler error due to different return type

In this prespective this is a SDK breaking change. When an existing application based on current SDK switch to new SDK (generated from this PR), if their application is using ApiRevisionInfoContract.apiVersionSet property then they need to change the type.

This issue can be addressed by bumping up the major version of the SDK.

As i mentioned earlier, the read-only properties id, name and type won't be available when customer access ApiRevisionInfoContract.apiVersionSet, right?

application code using current sdk

ApiRevisionInfoContract revisionContract = ...; System.out.println(revisionContract.id); // no compiler error

application code using new sdk (based on this PR) [broken]

ApiRevisionInfoContract revisionContract = ...; System.out.println(revisionContract.id); // compiler error, id property does not exists.

again if we bump up SDK version then this is fine.

Also we need ARM review because there is a new swagger apimversionsets.json, this is the first PR adding this swagger. So as per the established process, it is required to have this sign-ed off by ARM in this repo. I'm sending an email thread requesting ARM to take a look.

@anuchandy - I think what @darrelmiller is saying is that at GA, customer could not update/assign the value of id, name, type since they were read only. Swagger didnt reflect it. And so now, swagger is updating the description correctly to reflect the service state. If true, this is not a breaking change, since it would have never worked for the customer even if he tried to update.

thanks @ravbhatnagar got it. Still when customer compiles existing application (that was based current SDK) with the new sdk (generated from this PR), they will see compiler error. That should be fine given it's a side effect of correcting the swagger to reflect actual service state.

@anuchandy The current SDK is from March 2017 and is a preview https://www.nuget.org/packages/Microsoft.Azure.Management.ApiManagement/3.4.0-preview

@darrelmiller thanks for letting me know. Based on the process we established, i'll add potential SDK breaking changes tag for future reference.

Once we conclude the below discussion with ARM team, will merge this PR.

anuchandy · 2018-02-14T18:50:51Z

@ravbhatnagar please take a look at new swagger and breaking change in existing stable api version

ravbhatnagar

Looks good, just one comment

ravbhatnagar · 2018-02-16T00:43:56Z

+        }
+    },
+    "paths": {
+        "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/api-version-sets": {


@darrelmiller - is this resource type already supported on the service side?

The resource type names should be lower camel cased and only contain alphanumeric characters. Which is why I was checking.

@ravbhatnagar Are you saying that path segment api-version-sets should actually be apiVersionSets ? It is currently implemented as the former, but we could change it and make sure will still support the old value as well so we don't break any existing users.

@ravbhatnagar We can do this rename in our 2018-01-01 version which is what we are building the new .net client against.

@darrelmiller - sounds good. we can target this change in the new api-version.

ravbhatnagar · 2018-02-21T02:16:52Z

Signing off!

Adding vhdFormatType and isHA properties

darrelmiller added 7 commits February 8, 2018 20:38

Added ApiVersionSets

6b255d0

Merge remote-tracking branch 'upstream/master' into dm/versionsets

84cbee3

Fixes based on CR

5fec97d

Merged with master

74fbf1f

Refactored JSON Schemas for payloads

0aed758

Merge remote-tracking branch 'upstream/master' into dm/versionsets

cc6f70e

fixed names and reference

8578f92

azuresdkci assigned anuchandy Feb 13, 2018

anuchandy requested changes Feb 13, 2018

View reviewed changes

Fixed reference to schema for ApiVersionSets

e1f8c06

Fixed ApiVersionSetCreate example

0c42317

anuchandy reviewed Feb 14, 2018

View reviewed changes

anuchandy added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Feb 14, 2018

anuchandy requested a review from ravbhatnagar February 14, 2018 18:37

ravbhatnagar reviewed Feb 16, 2018

View reviewed changes

anuchandy added the potential-sdk-breaking-change label Feb 16, 2018

ravbhatnagar added ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review Conditionally-Merged and removed WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Feb 21, 2018

anuchandy approved these changes Feb 21, 2018

View reviewed changes

anuchandy merged commit afb3ee8 into Azure:master Feb 21, 2018

solankisamir mentioned this pull request Mar 1, 2018

ApiManagement: Rename ResourceType api-version-sets to apiVersionSets #2570

Closed

mccleanp pushed a commit that referenced this pull request Mar 23, 2022

Merge pull request #2483 from Azure/test

956e39c

Adding vhdFormatType and isHA properties

Conversation

darrelmiller commented Feb 13, 2018 • edited by azuresdkci Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR information

Quality of Swagger

Uh oh!

AutorestCI commented Feb 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Automation for azure-sdk-for-python

Uh oh!

AutorestCI commented Feb 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Automation for azure-sdk-for-go

Uh oh!

anuchandy left a comment

Choose a reason for hiding this comment

Uh oh!

azuresdkciprbot commented Feb 13, 2018

Uh oh!

azuresdkciprbot commented Feb 14, 2018

Uh oh!

darrelmiller commented Feb 14, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anuchandy commented Feb 14, 2018

Uh oh!

ravbhatnagar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ravbhatnagar commented Feb 21, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

darrelmiller commented Feb 13, 2018 •

edited by azuresdkci

Loading

AutorestCI commented Feb 13, 2018 •

edited

Loading

AutorestCI commented Feb 13, 2018 •

edited

Loading