Fix for https://github.com/Azure/azure-rest-api-specs/issues/2907

[naveedaz]

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.
  • [X ] 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-python

The initial PR has been merged into your service PR:
Azure/azure-sdk-for-python#2065

[AutorestCI]

Automation for azure-sdk-for-go

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-go#1755

[azuresdkciprbot]

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:

💡 Please review potentially introduced Error(s)/Warning(s): Analysis Report 💡

File: specification/web/resource-manager/readme.md
Before the PR: Warning(s): 792 Error(s): 22
After the PR: Warning(s): 793 Error(s): 22

AutoRest Linter Guidelines | AutoRest Linter Issues | Send feedback

Thanks for your co-operation.

[AutorestCI]

Automation for azure-libraries-for-java

The initial PR has been merged into your service PR:
AutorestCI/azure-libraries-for-java#4

[AutorestCI]

Automation for azure-sdk-for-node

The initial PR has been merged into your service PR:
Azure/azure-sdk-for-node#2612

[naveedaz]

@dsgouda Please review code and merge.

[jhendrixMSFT]

Does "x-ms-long-running-operation: true" need to be added to this (and the other) operation?

[dsgouda]

Hmm... not sure if we have long running get operations but in this case it does make sense to have one
@fearthecowboy can you take a look?

[dsgouda]

Need some additional feedback

[dsgouda]

Hmm... not sure if we have long running get operations but in this case it does make sense to have one
@fearthecowboy can you take a look?

[fearthecowboy]

Long running is only needed if the service isn't going to return right away -- 201 Created signifies the creation of a new resource, but if it's instantaneous (or close enough) and the service doesn't return a Location header, then LRO isn't required or useful.

And, this is a GET operation, which does not infer creation of a resource (ie, PUT) , nor the beginning of a request to process something (ie, an update/operation via PUT/POST)

I didn't see a state in the model definition for SiteSourceControl

Hey @ravbhatnagar -- Should they not be just adding some kind of provisioning state to the response object in this case (to support the scenario where the GET operation is called on a resource that isn't finished creating) -- or some other alternative?

[naveedaz]

@suwatch (API owner) Can you please comment on the concerns here.
@fearthecowboy, @jhendrixMSFT FYI the API has been behaving like this since 2015. So even if the behavior is incorrect it is currently how it is implemented. We recently found out that the response codes were missing from Swagger, because customers would see these response codes and the clients would fail.

[suwatch]

This is a long running and could last for minutes/hours depending on user's deployment artifact. As part of our GET, we do return ProvisioningState to indicate InProgress/Success/Failed. Hope I answer the question about the api.

[dsgouda]

1. If provisioning state is being returned, it has not been modeled
2. The GET doesn't actually create a resource as indicated by 201 Created or 202 Accepted status codes as @fearthecowboy pointed

Also, If I understand correctly the deployment (which is PUT/POST operation) must be long running and not the GET operation itself

[suwatch]

I understand your points. BTW, this long-running operation api works fine with ARM template engine since day one per https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-async-operations. The GET may return 202 if not completed. I think the missing part is that if the GET were called by clients other than ARM template engine, we should not be returning 201 or 202, correct?

If the request is still running, you receive a status code 202. If the request has completed, your receive a status code 200, and the body of the response contains the properties of the storage account that has been created.

[fearthecowboy]

FYI the API has been behaving like this since 2015

So, the current SDKs must be broken, for the GET operations. The question is, what should we do now?

The Client Runtime doesn't have any support for GET with LRO.

lemme go ping a couple people.

[fearthecowboy]

I've talked with @ravbhatnagar over in ARM -- he agrees that we don't really want to fix the client SDK generation to support this pattern. This is not consistent with API guidelines at all.

If this is what it's doing today; then fine -- write the swagger so that it's correct, and this behavior should be corrected in a subsequent API Version -- GET operations should not be returning 201 or 202.

Since we're not going to change the client generation, marking the APIs as x-ms-long-running isn't applicable, and the resultant calls will not successfully poll on the Location header. If the body returned by 201/202 doesn't contain the partially completed model, the resultant object will most definitely be incomplete. (Note that this is a disservice to your customers, which is why this should be corrected in a subsequent API version)

@dsgouda -- can you file a bug in the Linter to add a new ARM rule to that prohibits x-ms-long-running on GET operations

[dsgouda]

Approving this PR only as an accurate representation of the service today but this is against guidelines; will open an issue against this

[naveedaz]

@fearthecowboy Thanks for the review. Please assign the new issue to @suwatch

[dsgouda]

Opened issue to fix the service here and issue to implement a linter rule here