Breaking changes in API

[mikhailshilkov]

Let's collect breaking changes in stable API as we upgrade periodically.

The first batch (see #122 for discussion):

• CDN removed properties from a few latest versions PR in specs. In the description, they claim that those versions weren't released yet, so apparently we need to adopt a notion of release in our pipeline. A working theory is that a version isn't released unless it's published in the "README". And indeed, those versions were not in here until a week ago. We should validate this across the repo.

• Security renamed their types to avoid the word "whitelist" PR in specs. They confirm it's breaking but shipped for language-usage reasons.

• Storage cache fixed something about discrimination properties PR is specs. There's no explanation in the PR, so I asked for one, but it looks like this may be a bug fix in their terms, see this other PR.

In all three cases, Microsoft's automation detected the changes as breaking but the reviewers went ahead regardless.

Two new breaking changes on 2020-08-24 (see #131):

• C# namespace alias changed from AAD to Aad this is because a new spec file was added and our codegen took the alias from this new file, not the old file. If this happens after the release, we may want to pin the alias in our code.

• A resource SubscriptionAlias is renamed to Alias. This is a breaking change and clearly marked so in the original PR. They let it through because

  This is newly added version which is added last week. No SDK has been released yet for this version and API is not live yet for real customers, only internal testing users are using it.

  I guess it would be okay for us to release this breaking change with the same note.

Another breaking change on 2020-08-27 (see #140):

• A property sharedPrivateLinkResources was removed from Microsoft.Search stable API version 2020-03-13. The change comes from this PR, they acknowledge it's breaking, but still go ahead. Also, they mention they checked whether Terraform is impacted and it's not. I guess we should get to a position when they start checking Pulumi too. 😄

Another breaking change on 2020-09-03 (see #159):

• A bunch of properties was made read-only in HybridCompute/MachineProperties and HybridCompute/MachineExtensionInstanceView. The upstream PR says:

  although at the spec level this is a breaking change, from a codgen perspective these APIs have never really been released and from the service perspective, if these properties were supplied in a request, they would be ignored so the impact is incredibly minimal/non-existent.

Two more breaking changes on 2020-09-07 (see #166):

• This PR pushed a new version of Microsoft.Devices/2020-03-01 to the deviceprovisioningservices folder. However, there is an existing version of Microsoft.Devices/2020-03-01 in the iothub folder and their definitions overlap. In particular, CertificateProperties has no certificate property in the former but does have it in the latter. This caused us to remove the property from our SDK.

• Machine learning services removed several resource properties from PrivateEndpointConnection in this PR:

  They are not a breaking change to our python sdk(currently we only support python sdk). It's more like a correction. Because the PrivateEndpointConnection never supports Identity, Sku all that stuff in our services, so when I try to autorest with the current swagger, I found the issue therefore made this change. Hope it explains better the motivation of the breaking change

Another breaking change on 2020-09-15 (see #191):

• One breaking change in the latest NetApp stable version (upstream PR). Accepted with a comment

  Note the feature is in preview. the spec is new-ly created and generated SDK's have not been released yet, may be considered breaking but addresses a bug that we would like to fix.

One breaking change on 2020-10-13 (see #283):

• A breaking change in HubRouteTable: API definition fixed to match previous versions and the API behavior, source

A breaking change on 2020-10-29 (see #309):

• VirtualMachineScaleSetVMExtension removed location and tags, source

A breaking change on 2020-10-30 (see #310):

• Properties renamed in Marketplace resources to match the service behavior, source

A breaking change on 2020-11-04 (see #318):

• Properties removed from OperationalInsights, no comment yet, source

A breaking change on 2020-11-05 (see #323):

• Several things changed in Marketplace 2020-01-01, source

A breaking change on 2020-11-10 (see #329):

• expressRouteGatewayBypass property removed from the latest Network version, source

A breaking change on 2020-11-13 (see #344):

• Several breaking changes in the Marketplace RP source

A breaking change on 2020-11-13 (see #346):

• Azure renamed Attestation version 2018-09-01 to 2018-09-01-preview, source

A breaking change on 2020-11-17 (see #355):

• Several changes in OperationalInsights version 2020-10-01 which "not opened yet to customers", source

A breaking change on 2020-11-19 (see #357):

• Several properties removed from Virtual Network Peering, source

A breaking change on 2020-11-20 (see #358):

• A property renamed in Operational Insights, source

Two breaking changes on 2020-11-25 (see #364):

• Type changes in Storage Import Export, source
• Type changes in Marketplace, source

One breaking change on 2020-12-06 (see #377):

• Cost management ExportExecution changed from Resource to ProxyResource, source

One breaking change on 2020-12-09 (see #383):

• Several properties made readonly in Datadog, source

One breaking change on 2020-12-18 (see #411):

• Several changes in Microsoft.AAD/DomainServices, source

One breaking change on 2020-12-24 (see #419):

• Several changes in Healthbot, claiming that "the service is not publicly exposed yet and is still being tested" source

Two breaking changes on 2021-01-06 (see #438):

• Correctness fix in SignalR (source)
• Changes in Cost Management (source)

Two breaking changes on 2021-01-09 (see #443):

• Correctness fix in Analysis service (source)

One breaking change on 2021-01-11 (see #445):

• Correctness fix in Insights (source)

Two breaking change on 2021-01-14 (see #450):

• KeyVault (source)
• Cost Management (source)

One breaking change on 2021-01-21 (see #463):

• ActionRule renamed to Action in operational (security) insights (source)

One breaking change on 2021-01-22 (see #466):

• Compute/V20190701 - old API aligned with actual service behavior (source)

Two breaking changes on 2021-01-26 (see #479):

• Cdn (source)
• ImportExport (source)

Two breaking changes on 2021-01-30 (see #491):

• Confluent (source)
• StorageCache (source)

Three breaking changes on 2021-02-04 - all are "swagger correctness fixes" (see #500):

• DataBox (source)
• DataBoxEdge (source)
• MachineLearningServices (source)

One breaking change on 2021-02-11 (see #510):

• An enum value removed from a resource in Data Share (source)

Two breaking changes on 2021-02-21 (see #529):

• NetApp marked properties as read-only ANF-8872 Fix examples for integers Azure/azure-rest-api-specs#12367
• DataShare renamed enums Azure Data Share: Fix linter errors on x-ms-enum names Azure/azure-rest-api-specs#13040

A number of breaking changes, within several days before 2021-02-25 all described as correctness fixes (see #533):

• [Cognitive Services] change PEC actionRequired to actionsRequired Azure/azure-rest-api-specs#13066
• Correct the server version enum for MariaDB swagger Azure/azure-rest-api-specs#13031
• RoundTrip additional property and object additional property S360 fix by adding defaults and renaming respectively Azure/azure-rest-api-specs#12992
• Fix WebActivity dynamic authentication  Azure/azure-rest-api-specs#12384
• remove ssoContext and friendly name to match 2020-11-10 Azure/azure-rest-api-specs#13152
• [Fix S360 Broken Issues][HDInsight] Add some APIs and mark some properties as readOnly and provide default value Azure/azure-rest-api-specs#13082

[mikhailshilkov]

There is enough data for now, so I'll close the issue and won't update it anymore