Adding azure accounts APIs

[omarelhariry]

Latest improvements:

MSFT employees can try out our new experience at OpenAPI Hub - one location for using our validation tools and finding your workflow.

Contribution checklist:

• I have reviewed the documentation for the workflow.
• Validation tools were run on swagger spec(s) and have all been fixed in this PR.
• The OpenAPI Hub was used for checking validation status and next steps.

[msftclas]

All CLA requirements met.

[AutorestCI]

Automation for azure-sdk-for-js

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

[AutorestCI]

Automation for azure-sdk-for-python

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

[AutorestCI]

Automation for azure-sdk-for-ruby

Nothing to generate for azure-sdk-for-ruby

[AutorestCI]

Automation for azure-sdk-for-java

Nothing to generate for azure-sdk-for-java

[AutorestCI]

Automation for azure-sdk-for-go

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

[AutorestCI]

Automation for azure-sdk-for-node

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

[azuresdkci]

Can one of the admins verify this patch?

[yangyuan]

Hi @omarelhariry,

Have you reviewed changes with Azure API Review Board?
Feel free to contact me alias: yuanyang for further information.

[sarangan12]

Please check the output of https://travis-ci.org/Azure/azure-rest-api-specs/jobs/460227670 and fix the errors

[omarelhariry]

@sarangan12 Fixed, please check now.

[yangyuan]

Hi @omarelhariry, any update from API review board?

[omarelhariry]

I believe @sarangan12 review is sufficient for that as per their response.

[yangyuan]

Hi @omarelhariry,
API Review Board will review the API design which won't be fully reviewed in here.
For example they will probably suggest to use lowerCamelCase in actions like azureaccounts.

[AmirGeorge]

@yangyuan can you advise on what needs to be done here? The API returns a byte array (binary octet stream) in the response. How could we document its response here?

For context, we do not want to give the users visibility on how to deserialize the object. We just instruct our users to call that API to export the model and import it back in a different place. So we want to expose the minimum amount of details about the response format.

We tried have this as type array, type string & type object but the three fail giving the following error:

FATAL: System.Collections.Generic.KeyNotFoundException: Please specify a field with type of System.Byte[] to deserialize the file contents to
   at AutoRest.Modeler.OperationBuilder.VerifyFirstPropertyIsByteArray(CompositeType serviceType) in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\OperationBuilder.cs:line 441
   at AutoRest.Modeler.OperationBuilder.TryBuildStreamResponse(HttpStatusCode responseStatusCode, OperationResponse response, Method method, List`1 types, IModelType headerType) in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\OperationBuilder.cs:line 422
   at AutoRest.Modeler.OperationBuilder.BuildResponses(Method method, CompositeType headerType) in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\OperationBuilder.cs:line 336
   at AutoRest.Modeler.OperationBuilder.BuildMethod(HttpMethod httpMethod, String url, String methodName, String methodGroup) in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\OperationBuilder.cs:line 195
   at AutoRest.Modeler.SwaggerModeler.BuildMethod(HttpMethod httpMethod, String url, String name, Operation operation) in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\SwaggerModeler.cs:line 366
   at AutoRest.Modeler.SwaggerModeler.Build(ServiceDefinition serviceDefinition) in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\SwaggerModeler.cs:line 105
   at AutoRest.Modeler.Program.<ProcessInternal>d__2.MoveNext() in C:\Users\ci\AppData\Local\Temp\PUBLISHu1dw1\44_20171214T003644\autorest.modeler\src\Program.cs:line 60
--- 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: nodejs/imodeler1 - FAILED
FATAL: Error: Plugin imodeler1 reported failure.
Process() cancelled due to exception : Plugin imodeler1 reported failure.
  Error: Plugin imodeler1 reported failure.

[yangyuan]

Didn't test but I think it should be "format": "binary":

"PackageBinaryStreamObject": {
  "description": "The binary stream of the application package.",
  "type": "string",
  "format": "binary"
}

You should also add "content": "application/octet-stream" in response.

About "we do not want to give the users visibility on how to deserialize the object."
Why not just exclude this from swagger?

[AmirGeorge]

@yangyuan format binary is also not working, giving same error.

On adding content type, I already have:

"produces": [
          "application/octet-stream"
        ]

This is what we use in all our APIs to specify content type, is this what you mean? If there is another place to add "content": "application/octet-stream", please advise where.

[AmirGeorge]

And to answer your suggestion about excluding from swagger, we want the API to be visible for our users to call it but we do not want them to parse the response. Just call this API to export the app and import it elsewhere.

[yangyuan]

Weird, format binary is pretty common, surprisingly it's not supported.

But if that's the case, please refer to https://github.com/Azure/azure-rest-api-specs/blob/master/specification/cognitiveservices/data-plane/ComputerVision/stable/v1.0/ComputerVision.json
and use "type": "file"

For octet-stream, produces should be good enough.

[AmirGeorge]

@yangyuan a gentle reminder.

[yangyuan]

Please give me the exact command which causes the given error.
I started to think this might be other issues.

I checked travis log, didn't see this error.

[AmirGeorge]

I am not running any manual commands, I see the error in the automated PR build checks:
https://github.com/Azure/azure-rest-api-specs/pull/4524/checks?check_run_id=37479764

[yangyuan]

I pulled your branch, and run
autorest specification/cognitiveservices/data-plane/LUIS/Authoring/ --go
And I can see the exact same error.

Then I modify the "responses" of "/package/{appId}/versions/{versionId}/gzip" "/package/{appId}/slot/{slotName}/gzip" into below

        "responses": {
          "200": {
            "description": "The GZip binary stream of the published application package.",
            "schema": {
              "type": "file"
            }
          }
        }

And the problem gone.
Which means "type": "file" is valid, and I suspect "format": "binary" can work too.

[yangyuan]

I debugged a little bit, this is the solution.

        "produces": [
          "application/octet-stream",
          "application/json"
        ],

The problem is you define the response can only be application/octet-stream, so autorest try to assert that all response should be binary format and gives error. :)

[praries880]

error response modelling is not supported in autorest as of now.

[praries880]

Error responses are not supported by autorest as of now.

Add the error response to the default section. This applies all through this file.

[a-hohaze]

@praries880 Can you explain more as the SDKs were generated successfully and the error responses were included in the SDKs with no problem like here.

[omarelhariry]

Any update on this? @praries880

[cahann]

@praries880 any updates ? this is blocking our release before the holidays, appreciate if we can close on that before end of week

[a-hohaze]

We don't document 5xx responses for now

[omarelhariry]

But this one is thrown on purpose, it is not an arbitrary exception. Should it be removed too?