Update the SECP256K1 to P-256K

[prashanthyv]

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]

Automation for azure-sdk-for-ruby

Nothing to generate for azure-sdk-for-ruby

[AutorestCI]

Automation for azure-sdk-for-python

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

Command: python ./scripts/multiapi_init_gen.py azure-keyvault
Finished with return code 1
and output:

Was not able to extract api_version of v2016_10_01

[AutorestCI]

Automation for azure-sdk-for-node

A PR has been created for you based on this PR content.

Once this PR will be merged, content will be added to your service PR:
Azure/azure-sdk-for-node#2816

[AutorestCI]

Automation for azure-sdk-for-java

Nothing to generate for azure-sdk-for-java

[AutorestCI]

Automation for azure-sdk-for-go

A PR has been created for you:
Azure/azure-sdk-for-go#2705

[lmazuel]

@prashanthyv you introduce a breaking change in an old version of KV data-plane.
This means that anyone using this Swagger won't be able to send "SECP256K1" on the wire anymore, but instead they can send "P-256K". Is this really what the endpoint can handle?

Note that this Swagger is still used to communicate with Azure Stack, so it cannot be changed only for documentation purposes, it has to be exact accurate truth of the behavior of "2016-10-01". So this PR means "Sending SEC256K1 was never possible ever, and it was a typo in the spec, and if you try it now it will be refused by our endpoint". Is that so?

[RandalliLama]

@lmazuel Are you really saying that we can't even update comments/docs in the swagger, with no other changes, without breaking stack? In other words, we can't improve our existing documentation without breaking stack?

[msfcolombo]

@lmazuel, the SECP256K1 was supported during preview of the ECC feature. The service still supports that as a legacy feature, and will do so for some time. We don't use Swagger to implement the protocol at server side. This means old clients won't break. But we don't want new clients to send SECP256K1, and yes this can cause some headaches to people upgrading the client, but this is expected giving the preview nature of the feature. Do you have other suggestion?

[lmazuel]

@RandalliLama Swagger is not documentation of a RestAPI, it's a description of the exact behavior of a RestAPI. We do documentation out of that, which is not exactly the same thing. If you update a "description" node, that's pure documentation. If you update a class name or class content, it has to still reflect the reality of the behavior of the endpoint.
And it's not just Stack, we know direct users of Swaggers, and nothing force then to move to 7.0 until the API 2016-10-01 is deprecated. As long as your server support this API, Swagger needs to be truth of this endpoint.
There is syntax to still improve the documentation and still be accurate in representation, so I'm not concerned we'll find the right thing to do here. :). But it's probably not the initial PR suggestion.

@msfcolombo To rewrite what I understand (and then I can suggest the best way to do so):
In 2016-10-01, your server accepts 5 values for JsonWebKeyCurveName: "P-256", "P-384", "P-521", "SECP256K1" and "P-256K". But you want people to not use "SECP256K1", since it was preview, and it will be removed from the server at some point (undetermined yet). Your problem is that the documentation should not mention "SECP256K1" then.
Is this correct?

[msfcolombo]

@lmazuel Yes. We also don't want new versions of the client to send that value to the server. It's a breaking change from client's PoV.

[lmazuel]

@msfcolombo The approach we'd recommend with @johanste is to be transparent with customers (documentation, or Swagger users):

• Put the 5 values in the Swaggers. The current Swagger is wrong anyway, if you support "P-256K" and it's not here.
• Change the description of "SECP256K1" to something like "This is legacy configuration preview option and should not been used. It has been removed from recent API and might be decommissioned for this API version at any time. Use P-256K instead.". Put the wording in good English with scary warnings :)

I think this solves all your troubles:

• This is still backward compatible, and you don't break any people
• You provide a new value P-256K for people to use
• You still doesn't confuse people who could maintain old integration and would see this option in code. This is still documented. Out of documentation, this would become a documentation problem (which is a paradox here...). And you provide a solution to replace.
• You put in place a clear deprecation policy, in both documentation and SDK.

[prashanthyv]

@lmazuel - I don't mind updating the document to be backward compatible with respect to description.
I'll give a new PR.

Thanks

[lmazuel]

You don't have to do a new PR though, just update this one.

[lmazuel]

@prashanthyv update?

[azuresdkci]

Can one of the admins verify this patch?

[jhendrixMSFT]

@AutorestCI regenerate azure-sdk-for-go

[lmazuel]

@prashanthyv any update?

[prashanthyv]

@lmazuel - I thought Fernando already took care of this

[msfcolombo]

@prashanthyv Please drop this PR. We need to work on a different kind of change. Thanks.

[lmazuel]

Closing, feel free to re-open if necessary.