This repo needs a LICENSE.TXT file

Hi,
There should be a license file in this repo.

OperationId in GraphRbac 1.6 should not contains the word Operation

For instance "operationId": "ApplicationOperations_Create"
Should be "operationId": "Application_Create"

Since the Operations string is already added, this create weird class name with Autorest

Not that the operations id were fine in GraphRbac 1.42. Moreover, no other Swagger files use Operations in their operation id.

Add vmId to VirtualMachine

Per customer request: Azure/azure-sdk-for-java#619

The vmId field is available via REST - but it is not part of the SDK, to be more precise, the VirtualMachine object does not have a String vmId member, so when the REST call is returned, though available via REST, this value is not present on the virtual machine.
I need this value in order to uniquely identify this virtualMachine object - and I cannot use the id value since it is based on the vm's name.

@noaml2gitHub

Microsoft.Web 'User' has no scmUri item

Looking on resources.azure.com, you can see that User resources should have

{
  "id": ...",
  "name": "site",
  "type": "Microsoft.Web/sites/publishingcredentials",
  "location": "West US",
  "tags": {
    "hidden-related:/subscriptions/site/resourcegroups/site/providers/Microsoft.Web/serverfarms/site": "empty"
  },
  "properties": {
    "name": null,
    "publishingUserName": "$site",
    "publishingPassword": "key",
    "metadata": null,
    "isDeleted": false,
    "scmUri": "https://$site:[email protected]"
  }
}

However, the User model in https://github.com/Azure/azure-rest-api-specs/tree/master/arm-web/2015-08-01/swagger does not include scmUri.

Rest call to get VM w/ InstanceViews frequently returns 429 http status code

We're using the Azure SDK for Java 1.0-beta1 to create and retrieve VM Scale Sets and their associated VM instances in Azure. When we try to retrieve the instance view via the following SDK API call:

VirtualMachineScaleSetVMsOperations.list(, , null, null, "instanceView"). body

which will call the following Rest API:
https://management.azure.com/subscriptions/3557e83a-4f9f-490d-b681-90ab48e42182/resourceGroups//providers/Microsoft.Compute/virtualMachineScaleSets//virtualMachines?$expand=instanceView&api-version=2015-06-15

We often receive a 429 response code from Azure. Per the response headers, the value for the x-ms-ratelimit-remaining-subscription-reads is usually just short of 15000.

If there are almost 15000 remaining reads in the subscription, why are we getting a 429?

Also, in the headers, there is the Retry-After value which as I understand indicates how long we should wait before trying again. In most cases, it returns 120 seconds for that value. There have been some instances however, where it has return 1200 seconds. Twenty minutes is an incredibly long time to wait before retrying, especially when we are trying to report back to the user the status of the VMs (via the instance view) associated with their scale set.

Finally, one thing worth noting is that we only see this when we query Azure for the Scale Set VMs. We have several other processes that are querying Azure for other resources (load balancers, networks, security groups, VM Images, etc.) on the same subscription and have yet to encounter a 429 response with any of those. Also, the frequency of 429 responses goes up when we include the "InstanceView" in the request.

16 Similar Error Definitions with Same & Different Names in Swagger Specs

#16 Similar Error Definitions with Same & Different Names in Swagger Specs

There are several similar error definitions across Azure Swagger specs with same & different names.

In languages like Java and C#, similar error definitions with same & different names generate similar, multiple exception class definitions with same & different names in different name spaces.

Azure libraries for Java and other such languages carry a large surface area. A major part of API ergonomics is consistent naming themes, uniform definition of errors, uniform error handling, etc. Consistency makes it easier to use and memorize and also enables portability of learning. Having learnt a part of the library, developers can apply that learning across other parts of the libraries.

In Swagger specifications, designers should avoid duplicate definition of errors with same or different names. This, in turn, helps language-specific client library generators to choose an already existing exception class for each kind of abnormal condition that may cause an operation to thrown an error; define new exception classes, if needed.

The table below describes the current state - 16 similar error definitions with different names. These definitions can be represented with a single base error definition that comprises of {code, message, source-of-error, description, details} and Swagger specs MAY extend the definition to differentiate or pack additional info.

#	Service	Error	Code	Message	Source-of-error	Description	Details	Additional-info
1	CDN	ErrorResponse	Y	Y
2	Compute	ApiError	Y	Y	Y	Y	Y
3	Data Lake Analytics Account	Error	Y	Y	Y	Y	Y
4	Data Lake Job	Job Error Details			Y	Y	Y	Plenty of info
5	Data Lake Store Account	Error	Y	Y	Y	Y	Y	Y
6	Intune	Error	Y	Y
7	Mobile Management	ApiError	Y	Y
8	Network	Error	Y	Y	Y	Y	Y
9	Resources - Resources	ResourceManagementErrorWithDetails	Y	Y	Y	Y
10	Batch	DeleteCertificateError	Y	Y		Y	Y
11	Batch	JobSchedulingError	Y	Y		Y	Y
12	Batch	TaskSchedulingError	Y	Y		Y	Y
13	Batch	AutoScaleRunError	Y	Y		Y	Y
14	Batch	ResizeError	Y	Y		Y	Y
15	Batch	ComputeNodeError	Y	Y		Y	Y
16	Batch	BatchError	Y	Y		Y	Y

Two swagger files in the same folder

This dir contains two Swagger files:
https://github.com/Azure/azure-rest-api-specs/tree/master/arm-compute/2016-03-30/swagger
Is it intended?
I'm asking, because all other folders have only one Swagger file per dir.

Swagger Spec for Azure KeyVault is missing

Need a swagger spec for KeyVault.

Service Fabric Spec is Not ARM Spec

The host for the service fabric spec points to localhost and clearly couldn't be used in it's current form for code generation or external use. ~~It does not belong in the master branch until it is done.~~

~~@msjeffreychen, please move this to a branch or request that @amarzavery move this to a branch.~~

@msjeffreychen, please rename the folder from 'arm_servicefabric' to 'servicefabric'.

Ambiguous Permissions on Properties Complicate 75+ Create-OR-Update Operations

There are 75+ Create-OR-Update operations (across Azure Swagger specs) with ambiguous, undocumented permissions on properties (or parameters). If permissions on properties were unambiguously represented in Swagger specs then a generated client library could offer simpler programming experiences and improved predictability.

Let us look at one example.

VirtualMachines.createOrUpdate() - one of the parameters is VirtualMachine. Here is a breakdown of permissions of a subset of properties of VirtualMachine:

Property	Permission
id	read (4)
storageProfile::imageReference	read \| initialize (6)
storageProfile::osDisk::createOption	read \| initialize (6)
storageProfile::osDisk::vhd::uri	read \| initialize (6)
availabilitySet	read \| initialize (6)
hardwareProfile	read \| initialize \| update (7)
storageProfile::dataDisks	read \| initialize \| update (7)
storageProfile::osDisk::caching	read \| initialize \| update (7)
networkProfile	read \| initialize \| update (7)
tags	read \| initialize \| update (7)

Today, because of this ambiguous situation, when a developer calls the VirtualMachines.createOrUpdate() operation, the only available option is trial and error to find out what combinations of parameters work.

The good news is that it is possible to capture these permissions.

Swagger 2.0 says, "Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false " Some of Azure Swagger specs use this property.

readOnly can only represent read permissions but CANNOT represent read | initialize (6) OR read | initialize | update (7). A new Swagger extension will solve the problem -

Field Name	Type	Description
mutability	integer	Represents the permission of the property: -read (4) -initialize (1) -read \| initialize (6) -read \| initialize \| update (7) Default is read \| initialize \| update (7)

Capturing permissions on properties will simplify programming experiences and improve predictability across languages - C#, Java, Node, Python, Ruby, PHP, Go - and tools - PowerShell and cross-platform CLI.

Today, regardless of the ambiguous situation, hand-written PowerShell commandlets and cross-platform CLI commands absorb the complexity and simplify it for developers - there are two distinct paths for Create and Update:

PowerShell: Create a virtual machine that uses VirtualMachines.createOrUpdate()

PS C:\> New-AzureRmVM -ResourceGroupName $ResourceGroupName -Location $Location -VM $VirtualMachine

PowerShell: Update a virtual machine that uses VirtualMachines.createOrUpdate()

PS C:\> Update-AzureRmVM -ResourceGroupName "ResourceGroup11" -Name "VirtualMachine07" -VM $VirtualMachine

If permissions on properties were unambiguously represented in Swagger specs then a generated client library could offer simpler programming experiences and improved predictability.

Reference - today, there are 75+ such Create-OR-Update operations with such ambiguous permissions on properties

Authorization

RoleDefinitions.createOrUpdate()

Compute

Data Lake Store Account

Account.createOrUpdateFirewallRule()

DNS

Intune

Logic

Network

Notification Hubs

Redis

Redis.createOrUpdate()

Remote App

Collection.createOrUpdate()

ARM Resources - Locks

ARM Resources - Account

Scheduler

Search

Services.createOrUpdate()

SQL

SecurityAlertPolicy.createOrUpdate()

App Service - Web App

web: type error in Status in ServerFarmWithRichSku class

Hello,

I work in the MS Azure Python SDK team and I'm currently trying the Autorest generated version for Python,
I created a App Service Plan using this Python SDK generated from the Web Swagger file (rev. c81ae63) with the ServerFarms_CreateOrUpdateServerFarm method.
I got in result:

{
    "id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX/resourceGroups/test_mgmt_logic_test_logic90d30a9d/providers/Microsoft.Web/serverfarms/pyarmappserviceplan90d30a9d",
    "name": "pyarmappserviceplan90d30a9d",
    "type": "Microsoft.Web/serverfarms",
    "location": "West US",
    "tags": null,
    "properties": {
        "serverFarmId": 0,
        "name": "pyarmappserviceplan90d30a9d",
        "workerSize": 0,
        "workerSizeId": 0,
        "workerTierName": null,
        "numberOfWorkers": 0,
        "currentWorkerSize": 0,
        "currentWorkerSizeId": 0,
        "currentNumberOfWorkers": 0,
        "status": 0,
        "webSpace": "test_mgmt_logic_test_logic90d30a9d-WestUSwebspace",
        "subscription": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX",
        "adminSiteName": null,
        "hostingEnvironment": null,
        "hostingEnvironmentProfile": null,
        "maximumNumberOfWorkers": 1,
        "planName": "VirtualDedicatedPlan",
        "adminRuntimeSiteName": null,
        "computeMode": 0,
        "siteMode": null,
        "geoRegion": "West US",
        "perSiteScaling": false,
        "numberOfSites": 0,
        "hostingEnvironmentId": null,
        "tags": null,
        "kind": null,
        "resourceGroup": "test_mgmt_logic_test_logic90d30a9d"
    },
    "sku": {
        "name": "F1",
        "tier": "Free",
        "size": "F1",
        "family": "F",
        "capacity": 0
    }
}

Regarding the Swagger spec, "status" is an enum:

"status": {
              "description": "App Service Plan Status",
              "enum": [
                "Ready",
                "Pending"
              ],
              "type": "string",
              "readOnly": true,
              "x-ms-enum": {
                "name": "StatusOptions",
                "modelAsString": false
              }
            }

However, as you can see the status I got is 0, not a string in Ready or Pending.

Then the Python generated code is broken (I guess the C#, Java, etc. will be broken) too. Can you look at this?

At the same time, could someone from the team who own this file give me a status for it? Is it ready for a preview version in a generated client?

Thank you,

compute: spec missing for virtualmachines/{vm}/InstanceView

folks we're missing spec for

.../providers/Microsoft.Compute/virtualMachines/{vm}/InstanceView

as far as I can tell. Can someone verify? @huangpf

arm-logic/2015-02-01-preview missing $filter parameter for workflow trigger history

According to https://msdn.microsoft.com/library/azure/mt643788.aspx the 'Get trigger history for the workflow' action has a $filter parameter:

https://{endpoint}/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Logic/workflows/{workflowName}/triggers/{triggerName}/histories?api-version=2015-08-01-preview&$filter=status eq 'Succeeded'

However,

azure-rest-api-specs/arm-logic/2015-02-01-preview/swagger/logic.json

Line 966 in 48bc044

    
           "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Logic/workflows/{workflowName}/triggers/{triggerName}/histories": {

is missing the parameter in the definition.

Missing coverage for Azure SQL Management

Azure Ruby SDK has received feedback that the SQL management spec is missing needed operations. Please add these as soon as possible.

Issue: Azure/azure-sdk-for-ruby#307

compute: spec "Resource" shouldn't require location

In the spec for arm-compute, the "Resource" object specifies "location" as a required property when I believe it shouldn't.

See https://github.com/Azure/azure-rest-api-specs/blob/master/arm-compute/2015-06-15/swagger/compute.json#L4581

The "VirtualMachineExtension" object extends "Resource". However, "VirtualMachineExtension" does not always have "location" defined.

This is evident with an API call to
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/virtualMachines?api-version=2015-06-15
where the "resources" object in the JSON response contains an array of VM Extensions and each object in this array only has an id (i.e. no "location").

Document meaning of `-internal` and `-preview` version postfixes

Currently, it's unclear what these prefixes mean.
Is preview mean API could be changed or deprecated or it's in some kind of close beta?
Is private mean that only Microsoft employees can access it?

Azure Search Service API Spec Updates

It looks like only the Search Management API (https://msdn.microsoft.com/en-us/library/azure/dn832684.aspx) has a spec to date. It would be great to get an updated spec to include the entirety of the Search Search API (https://msdn.microsoft.com/en-us/library/azure/dn798935.aspx). This would further the efforts to expand the arm support being built out for the Go SDK as described here.

"name" field should be readonly in ResourceGroup object

The name field in ResourceGroup object is not readonly in the resources Swagger:
https://github.com/Azure/azure-rest-api-specs/blob/master/arm-resources/resources/2016-02-01/swagger/resources.json#L1980

But according to REST API that modify a ResourceGroup, there is no reason to do not make it read-only, since it's not documented as an input in the JSON body:
https://msdn.microsoft.com/en-us/library/azure/dn790525.aspx
https://msdn.microsoft.com/en-us/library/azure/dn790582.aspx

This will simplify SDK ResourceGroup constructor

Schema Difference Between Create and Update in Put Operations

This issue is related to issue #275.

Azure resource creates and updates are accomplished through HTTP PUTs. HTTP PUTs should function the same way in create as they do in update. Unfortunately, create operations don't always have the same semantics as an update.

I will use Azure Resource Group creation and update for an example. If I create a Resource Group with a location of westus, the resource group will be created with that location. If I then try to update the Resource Group to a location of eastus, I will receive a 409 status code. The location can only be set on create, but can't be updated. Clearly, this leads consumers of our generated code down a path of failure. We should have two different methods here, one for create and one for update.

The main issue with describing this in the spec is that create and update are both PUTs to the same URI. Thus, there is no way in Swagger to specify this type of behavior for parameters through separating this into a create and update operation with two separate schema.

Possible solutions:

We add any PUT which requires different schema for Create and Update for the same URI / Verb combination to x-ms-paths so that we can define two different operations for the same URI / Verb combination.
We add an extension to the original put that would specify the keys of the schema we'd like to omit from the update. My supposition here is that the update will always have a subset of the create schema.
Something else. Please suggest.

request for comment: @Azure/adx-sdk-team, @selvasingh

x-ms-operation-wrapper: Generating Wrapper methods for similar operations

It would be nice if we can generate a wrapper method for similar operations, that give a subset of the result or a filtered result based on the parameters provided to the method.

Let us consider ListBySubscription() and ListByResourceGroup(string resourcegroup) over
StorageAccounts. They both return StorageAccounts (same type) but different items due to scope.
It makes sense to group/wrap them together in a wrapper method. This gives us a benefit to autogenerate CLI/powershell commands from the wrapper method.

What would be the best way to describe this wrapping/grouping in an extension using swagger?

One approach that I can think of is: To annotate/tag every operation that needs to be wrapped with an extension named:

"x-ms-operation-wrapper": { 
     "WrappedOperationId": "OperationGroup_WrapperMethod",  
      "description" : "Description for the wrapper method"
}

. . .
"paths": {
    "/subscriptions/{subscriptionId}/providers/Microsoft.Storage/storageAccounts": {
      "get": {
        "tags": [
          "StorageAccounts"
        ],
        "operationId": "StorageAccounts_ListBySubscription",
        "description": "Lists all the storage accounts available under the subscription. Note that storage keys are not returned; use the ListKeys operation for this.",
        "parameters": [
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubscriptionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/StorageAccountListResult"
            }
          }
        },
>>> "x-ms-operation-wrapper": {
          "WrappedOperationId": "StorageAccounts_List"
         "description" : "Lists Storage accounts in a resource group if provided or in a subscription."
        },
        "x-ms-pageable": {
          "nextLinkName": null
        }
      }
    },
    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts": {
      "get": {
        "tags": [
          "StorageAccounts"
        ],
        "operationId": "StorageAccounts_ListByResourceGroup",
        "description": "Lists all the storage accounts available under the given resource group. Note that storage keys are not returned; use the ListKeys operation for this.",
        "parameters": [
          {
            "name": "resourceGroupName",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "The name of the resource group within the user's subscription."
          },
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubscriptionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/StorageAccountListResult"
            }
          }
        },
>>> "x-ms-operation-wrapper": {
          "WrappedOperationId": "StorageAccounts_List",
          "description" : "Lists Storage accounts in a resource group if provided or in a subscription."
        },
        "x-ms-pageable": {
          "nextLinkName": null
        }
      }
    }
. . .
}

Some rules will be enforced when this extension is applied. They are as follows:

The Wrapper method will have a union of all the methods as its parameters in the method signature.
It will route the call to the right method, based on matching parameter sets
- A required parameter in all the inner methods will be a required parameter on the wrapper method.
- If the parameter is required in one inner method and optional in another then that parameter will be optional parameter on the wrapper method.
The return type of the wrapper method will be the same as the return type of all the inner methods
All the inner methods should belong to the same operation group if they follow the Noun_Verb format. If the inner methods are operations on the client then it should be fine.
AutoRest will throw an exception during generation if:
- the return type of all the underlying methods is not the same (I am not sure if inheritance should be considered).
- All the inner methods do not belong to the same operation group

Let me know your thoughts on this.

Swagger spec for microsoft.web/connections is missing

microsoft.web/connections isn't included in the views.

Model definitions with allOf does not respect OPENAPI SPECIFICATION

If we look on Models with Composition and Models with Polymorphism Support examples in the OPENAPI SPECIFICATION (http://swagger.io/specification/), model definition contains only description and allOf fields. Of course, allOf includes object definitions and it is used to describe composition and inheritance. But in the Azure Specs we can see properties outside of allOf array, so it make issues for Swagger Codegen to generate the correct code.

For example, we can take a model from https://github.com/Azure/azure-rest-api-specs/blob/master/arm-network/2016-03-30/swagger/network.json :

     "ApplicationGatewayIPConfiguration": {
      "properties": {
        "properties": {
          "x-ms-client-flatten": true,
          "$ref": "#/definitions/ApplicationGatewayIPConfigurationPropertiesFormat"
        },
        "name": {
          "type": "string",
          "description": "Gets name of the resource that is unique within a resource group. This name can be used to access the resource"
        },
        "etag": {
          "type": "string",
          "description": "A unique read-only string that changes whenever the resource is updated"
        }
      },
      "allOf": [
        {
          "$ref": "#/definitions/SubResource"
        }
      ],
      "description": "IP configuration of application gateway"
    }

Swagger CodeGen will generate following incorrect code for Java :

@javax.annotation.Generated(value = "class io.swagger.codegen.languages.JavaClientCodegen", date = "2016-04-01T18:37:32.629+02:00")
public class ApplicationGatewayIPConfiguration extends SubResource  {

  private String id = null;

  /**
   * Resource Id
   **/

  @ApiModelProperty(value = "Resource Id")
  @JsonProperty("id")
  public String getId() {
    return id;
  }
  public void setId(String id) {
    this.id = id;
  }

/// Methodes 
/// ...

And if we are going to follow the specification and we will use model definition below :

        "ApplicationGatewayIPConfiguration": {
            "allOf": [{
                "$ref": "#/definitions/SubResource"
            },
            {
                "type": "object",
                "properties": {
                    "properties": {
                        "$ref": "#/definitions/ApplicationGatewayIPConfigurationPropertiesFormat"
                    },
                    "name": {
                        "type": "string",
                        "description": "Gets name of the resource that is unique within a resource group. This name can be used to access the resource"
                    },
                    "etag": {
                        "type": "string",
                        "description": "A unique read-only string that changes whenever the resource is updated"
                    }
                }
            }],
            "description": "IP configuration of application gateway"
        }

We will get the expected result :

@javax.annotation.Generated(value = "class io.swagger.codegen.languages.JavaClientCodegen", date = "2016-04-01T18:40:11.781+02:00")
public class ApplicationGatewayIPConfiguration extends SubResource  {

  private String name = null;
  private String etag = null;
  private String id = null;
  private ApplicationGatewayIPConfigurationPropertiesFormat properties = null;


  /**
   * Gets name of the resource that is unique within a resource group. This name can be used to access the resource
   **/

  @ApiModelProperty(value = "Gets name of the resource that is unique within a resource group. This name can be used to access the resource")
  @JsonProperty("name")
  public String getName() {
    return name;
  }
  public void setName(String name) {
    this.name = name;
  }

AutoREST supports both incorrect and correct versions.

17 App Service Operations Return Abnormal 404 and 409

#17 App Service Operations Return Abnormal 404 and 409

Numerous Create, Delete, Update and Reboot operations in the App Service Swagger spec return abnormal 404 and 409. Developers will not be able to differentiate request succeeded OR accepted versus resource was not found OR there is a conflict. When a resource is not found or there is a conflict, an exception will not be thrown.

    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "$ref": "#/definitions/Object"
        }
      },
      "202": {
        "description": "Operation is in progress",
        "schema": {
          "$ref": "#/definitions/Object"
        }
      },
      "400": {
        "description": "Bad request"
      },
      "404": {
        "description": "Not found"
      },
      "409": {
        "description": "Conflict"
      }
    },

If an operation encounters an abnormal condition that it cannot handle, it should throw an exception. If an operation is throwing an exception for an abnormal condition that we feel that developers should consciously decide how to handle, then throw a checked exception in a client library with sufficient information. A client library cannot through an exception if an operation does not define errors in Swagger.

Are these 404 and 409 definitions intentional?

Here is a SAMPLE list of those 404 and 409 occurrences -

Link to swagger spec broken

Hey guys,

This page supposedly giving the link to the Swagger 2.0 spec is linked to in this doc, but appears to 404:

https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Swagger-spec2.0

Thanks,

Steven

Service Fabric Swagger Spec Does Not Define Errors

Service Fabric Swagger spec does not define any errors.

However, Service Fabric REST API throws many exceptions.

Child links and SDKs

It will be easiest to explain with an example. Say you want to get the private IP address of a VM.

To do this, you need to Get the VirtualMachine, look at the NetworkProfile, pick one of the NetworkInterfaceReferences and then do a GET on that URL to retrieve the actual NIC configuration, including ip configurations and their private addresses.

Unfortunately, this is cumbersome, at least in the Go SDK. The Get operation for the InterfacesClient takes resourceGroup and interfaceName. This requires me to manually string decompose the InterfaceReference from the VM response.

What is the recommendation for how SDKs should handle this? How do the other SDKs handle this scenario?

need a swagger for Azure Billing REST API

Being that we spend many thousands of dollars on Azure each month, we are interested in producing custom reports of the usage. I would like to use the relatively new Azure Billing REST API for this. I am looking for a Swagger definition of these APIs. I could probably help fill them out if the stubs get created in a git branch.

Allow api-version to be optional for ResourceManagementClient

With the current client, there is no way for users to override api-version in a get resource call. For example, if I want to get a storage account using the latest api version supported by the RP (Microsoft.Storage), I can't do this

Not setting BaseUri in the Spec is translated to setting BaseUri to http://localhost by default

For Key Vault SDK, some of the public APIs accept a key ID or secret ID, which is made up of a vault URL, key/secret name and the collection title.
E.g.:
public async Task GetKeyAsync(string keyIdentifier, CancellationToken cancellationToken = default(CancellationToken))

Here is an example of a KeyIdentifier: https://vaultName.vault.azure.net:443/keys/keyName/keyVersion

The default baseUri should be set to an empty string if not provided in the spec to support the above scenario.

92 variations of list operation names across Azure Swagger specifications

One More Thing ...

There are 92 other variations of list names

The good news is that these list names can be modeled as CollectionObject.list() and CollectionObject.listByResourceGroup().

Example One -

/catalog/usql/databases/{databaseName}/assemblies": { 
  "get": { 
     "tags": [ 
     "Catalog" 
   ], 
  "operationId": "Catalog_ListAssemblies", 
  "description": "Retrieves the list of assemblies from the Data Lake Analytics catalog.

This can be modeled as Assemblies.list().

Example Two -

"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DataLakeAnalytics/accounts/{accountName}/StorageAccounts/": {
  "get": {
  "tags": [
     "Account"
  ],
  "operationId": "Account_ListStorageAccounts",
  "description": "Gets the first page of Azure Storage accounts, if any, linked to the specified Data Lake Analytics acco

This can be modeled as StorageAccounts.list().

92 other variations of list names by Swagger specs are -

Authorization -

Batch Management

listKeys()

CDN

Compute

Data Lake Analytics

Data Lake Store

DNS

Logic

Network

Notification Hubs

Redis

listKeys()

Remote App

Resources

Scheduler

Storage

listKeys()

Web

Batch

Compute: Standard_D* VM sizes missing

azure-rest-api-specs/arm-compute/2015-06-15/swagger/compute.json

Lines 1896 to 1917 in 3533959

    
           "enum": [ 
        
             "Basic_A0", 
        
             "Basic_A1", 
        
             "Basic_A2", 
        
             "Basic_A3", 
        
             "Basic_A4", 
        
             "Standard_A0", 
        
             "Standard_A1", 
        
             "Standard_A2", 
        
             "Standard_A3", 
        
             "Standard_A4", 
        
             "Standard_A5", 
        
             "Standard_A6", 
        
             "Standard_A7", 
        
             "Standard_A8", 
        
             "Standard_A9", 
        
             "Standard_G1", 
        
             "Standard_G2", 
        
             "Standard_G3", 
        
             "Standard_G4", 
        
             "Standard_G5" 
        
           ],

Mark preferred version of API

Some APIs have multiple swagger files documenting different versions.
In my service, by default show preferred version of API.
Could you please mark preferred version somehow?
For example, Git support symlinks, so you can make $api/preferred/ point to dir with preferred version.

Missing property in "Get information from template"

Hi,

I currently need to get informations from a deployment, so I use:
https://msdn.microsoft.com/en-us/library/azure/dn790565.aspx

I discovered that the resulting JSON contains a outputResources node than the official documentation doesn't have:

"outputResources":[  
         {  
            "id":"Microsoft.Compute/virtualMachines/azlmaz3"
         },
         {  
            "id":"Microsoft.Compute/virtualMachines/azlmaz3/extensions/install_apache"
         },
         {  
            "id":"Microsoft.Compute/virtualMachines/memcached0"
         },

The information inside is very valuable for me! Since I use a Swagger generated client and since the Swagger file does not contain it neither, I cannot use it currently.

I can do a PR to add this node, but I would like someone from the Resource team to give a status about this node.

Thank you!

Composite spec shall not hard code the base paths for child specs.

For example: https://github.com/Azure/azure-rest-api-specs/blob/master/arm-compute/compositeComputeClient.json

{
    "info": {
        "title": "ComputeManagementClient",
        "description": "Composite Swagger for Compute Client"
    },
  "documents": [
    "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/2015-06-15/swagger/compute.json",
    "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/2015-11-01-preview/swagger/containerService.json"
  ]
}

The URL part: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute needs to be changed to local drive location in local development, and then in PR it needs to be replaced by URLs.

It's very rigid, and error prone.

Please do not let AutoRest spec include base URL parts, and the paths inside shall be relative to the location of the composite spec files, i.e.

    "2015-06-15/swagger/compute.json",
    "2015-11-01-preview/swagger/containerService.json"

Missing Error Definitions or References in 9 Swagger Specs

Notification Hubs REST API throws several error codes however its Swagger does not define any of these.

Search REST API throws several error codes however its Swagger does not define any of these.

Azure Active Directory Graph API throws several error codes however its Swagger does not define any of these.

So on and on ...

CRP and NRP Swagger are not accurate for NIC/IPConfiguration's primary fields

The core details are here: Azure/azure-sdk-for-go#259 (comment)

The Swagger spec for Compute Instance -> NetworkProfile NIC -> primary is not correct -- in that [someone] is not populating the "primary" field for an Interface in my VM's NetworkProfile.

The Swagger spec for Network's Interface -> IPConfiguration -> primary field does not exist.

The net result of this is that I can NOT accurately write code to say... place a VM in a load balancer backend pool because I have no way of determining which NIC is primary, or which ip configuration on the NIC is primary.

I'm currently "working around" this by assuming that there is only one NIC and only one IP Configuration... which is probably fine for my use case, but we should still fix this.

Include a Definition of an ARM Template

I logged an issue against the azure-sdk-for-go, but they pointed me here.

The generated SDK does not define a type that represents an ARM template. It can be approximated based on existing types (mostly), but it would be better to a have a definitive way to represent one.

Storage: wrong spec for CheckNameAvailabilityResult

azure-rest-api-specs/arm-storage/2015-05-01-preview/swagger/storage.json

Lines 407 to 412 in 4be6f83

    
           "CheckNameAvailabilityResult": { 
        
             "properties": { 
        
               "nameAvailable": { 
        
                 "type": "boolean", 
        
                 "description": "Gets a boolean value that indicates whether the name is available for you to use. If true, the name is available. If false, the name has already been taken or invalid and cannot be used." 
        
               },

:

https://msdn.microsoft.com/en-us/library/azure/mt163642.aspx :

nameAvailable should be string, not boolean. Currently blocking Azure/azure-sdk-for-go#210

Security Error Channeled Through HTTP 200

Security Principal Operation Error is channeled through HTTP 200 - See Collection.addUser() in Remote App Swagger spec.

      "200": {
        "description": "",
        "schema": {
          "$ref": "#/definitions/SecurityPrincipalOperationErrorDetails"
        }

Is this intentional?

OpenAPI specs that are not complete should not be in master

OpenAPI specs that are not 100% complete should not be included in the master branch. They should be off in a feature branch to ensure they are not included in code generation.

@brjohnstmsft you might have some feedback here as well.

VirtualMachine update fails unexpectedly

According the REST standard, a PUT update should accept all unchanged values and not change anything on the server side.

A customer is doing an update right after a GET, and a very vague error message is thrown:

InvalidRequestContent: The request content was invalid and could not be deserialized: 'Could not find member 'resources' on object of type 'ResourceDefinition'. Path 'resources', line 1, position 1046.'.

.......,"resources":[{"properties":{"publisher":"Microsoft.Azure.Diagnostics","type":"IaaSDiagnostics","typeHandlerVersion":"1.5","autoUpgradeMinorVersion":true,"provisioningState":"Succeeded"},"id":"/subscriptions/xxxxxx-xxxxxxx-xxxx-xxxx-067585c4a76a/resourceGroups/LBGroup/providers/Microsoft.Compute/virtualMachines/VM1/extensions/Microsoft.Insights.VMDiagnosticsSettings","name":"Microsoft.Insights.VMDiagnosticsSettings","type":"Microsoft.Compute/virtualMachines/extensions","location":"westus","tags":******************}

web: type error in sslState in HostNameSslState class

Hello,

I work in the MS Azure Python SDK team and I'm currently trying the Autorest generated version for Python,
I'm just trying to do a get a a website using webspace+name using this Python SDK generated from the Web Swagger file (rev. c81ae63) with the "Sites_GetSite method.
I got in result for hostNameSslStates

    "hostNameSslStates": [
      {
        "name": "mysite.azurewebsites.net",
        "sslState": 0,
        "ipBasedSslResult": null,
        "virtualIP": null,
        "thumbprint": null,
        "toUpdate": null,
        "toUpdateIpBasedSsl": null,
        "ipBasedSslState": 0,
        "hostType": 0
      },

Regarding the Swagger spec, "sslState" is an enum:

"sslState": {
          "description": "SSL type",
          "enum": [
            "Disabled",
            "SniEnabled",
            "IpBasedEnabled"
          ],
          "type": "string",
          "x-ms-enum": {
            "name": "SslState",
            "modelAsString": false
          }
        },

However, as you can see the sslState I got is 0, not a string.

It's the second bug (after #137) I open on the web file so far, is this possible to have at least a confirmation or state from the web team about this?
Thank you,

Delete Redis Cache Returns Abnormal 404

Delete a Redis Cache returns an abnormal 404. In this case, developers will not be able to differentiate request accepted vs. resource was not found. When a resource is not found, an exception will not be thrown.

    "responses": {
      "200": {
        "description": ""
      },
      "202": {
        "description": ""
      },
      "404": {
        "description": ""
      }
    }

If a method encounters an abnormal condition that it cannot handle, it should throw an exception. If a method is throwing an exception for an abnormal condition that we feel that developers should consciously decide how to handle, then throw a checked exception in a client library with sufficient information. A client library cannot through an exception if a method does not thrown an exception.

Is this 404 definition intentional?

Inconsistent list operations across Azure Swagger specifications

Azure libraries for Java and other languages carry a large surface area. A major part of API ergonomics is consistent naming themes. Consistency makes it easier to use and memorize and also enables portability of learning. Having learnt a part of the library, developers can apply that learning across other parts of the libraries.

Specifications should use a consistent set of simple names for list operations across resources and resource providers, and offer list operations where developers are expecting:

list() // list all 'resources' under a subscription
listByResourceGroup() // list all resources in a resource group within a subscription

Where applicable, code gen may add next to support pagination:

listNext() // list next for list() generated by code gen
listByResourceGroupNext() // list next for listByResourceGroup() generated by code gen

Examined three Swagger specs - compute, storage and network. Samples quoted below are representative samples of a larger number of such inconsistencies. There might be additional inconsistent patterns if someone were to examine other Swagger specs - say listBySubscription() or listInSubscription() or listInResourceGroups() or listAtResourceLevel() or listLocations().

`list()` and `listAll()` used interchangeably with the same semantics

Examples -

StorageAccounts.list() // list all storage accounts under a subscription
VirtualMachines.listAll() // list all virtual machines in a subscription
VirtualNetworks.list() // list all virtual networks in a subscription
ExpressRouteServiceProviders.list() // List all Express Route Service Providers, independent of a resource group or a subscription

`list(string)` and `listByResourceGroup(string)` are used interchangeably with the same semantics

Examples -

VirtualNetworks.list(resourceGroupName) // list all virtual networks in a resource group within a subscription
StorageAccounts.listByResourceGroup(resourceGroupName) // list all storage accounts in a resource group within a subscription

`listAll()` is missing where developers would expect them

Examples -

VirtualMachineImages.listAll() // list all virtual machine images. To realize this functionality, additional coding is required:

var locations = getAzureLocations()
for each (var location in locations) {
    var publishers = images.listPublishers(location.name)
        for each (var publisher in publishers) {
            var offers = images.listOffers(location.name, publisher.name)
                for each (var offer in offers) {
                    var skus = images.listSkus(location.name, publisher.name, offer.name)
                        foreach (var sku in skus) {
                            images.list(location.name, publisher.name, offer.name, sku.name)
                }
            }
        }
    }
}

VirtualNetworkGateways.listAll() // list all virtual network gateways

Complicated `list()` names with complex parameters

Examples -

listVirtualMachineScaleSetVMNetworkInterfaces(resourceGroupName, virtualMachineScaleSetName, virtualMachineIndex) // list all virtual network interfaces in a virtual machine within a virtual machine scale set

Resources_CreateOrUpdate

When using the ResourcesOperations.create_or_update method in the Python SDK to set tags on an existing resource a CloudError is raised because the operation returns HTTP Code 202 (Accepted). The operation is successful in that the resource has the correct tags after the call.

The swagger for this command only lists 200 and 201 as valid response codes. Typically 202 kicks off a long running operation which (hopefully) returns a 200. It seems that 202 should be added as an acceptable response and that (possibly) the operation be modeled as a LRO so that the client is informed whether the operation succeeded or failed.

Enum options does not respect real Azure API values

There are sometimes some difference between enum options in specs and values which we have in API response.

For example, for storage ( https://github.com/Azure/azure-rest-api-specs/blob/master/arm-storage/2016-01-01/swagger/storage.json ):

 "statusOfPrimary": {
          "readOnly": true,
          "type": "string",
          "description": "Gets the status indicating whether the primary location of the storage account is available or unavailable.",
          "enum": [
            "Available",             // Issue: Capital A
            "Unavailable"           // Issue:  Capital U
          ],
          "x-ms-enum": {
            "name": "AccountStatus",
            "modelAsString": false
          }
        },

but https://management.azure.com/subscriptions/[subscripbtionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Storage/storageAccounts/[storageAccountName]?api-version=2015-05-01-preview returns:

{
  "id": "/subscriptions/[subscriptiopnId]/resourceGroups/[res]/providers/Microsoft.Storage/storageAccounts/publicommons",
  "location": "West Europe",
  "name": "[storageAccountName]",
  "properties": {
    "accountType": "Standard_LRS",
    "creationTime": "2016-04-22T13:11:17.1629017Z",
    "primaryEndpoints": {
      "blob": "https://[storageAccountName].blob.core.windows.net/",
      "file": "https://[storageAccountName].file.core.windows.net/",
      "queue": "https://publicommons.queue.core.windows.net/",
      "table": "https://publicommons.table.core.windows.net/"
    },
    "primaryLocation": "West Europe",
    "provisioningState": "Succeeded",
    "statusOfPrimary": "available" // Issue: only lowercase letters
  },
  "tags": {},
  "type": "Microsoft.Storage/storageAccounts"
}

To have Available as Enum option and available in the response value makes difficulties with deserialization in case-sensetive languages.

GrarphRBAC 1.42 not yet supported?

Hi,

I get a

{"odata.error":{"code":"Request_InvalidDataContractVersion","message":{"lang":"en","value":"The specified api-version is invalid. The value must exactly match a supported version."}}}

error when I tried to use the GraphRBAC 1.42 Swagger.

Has this API version disappeared?

Swagger spec doesn't account for paging.

In the swagger spec, for networking for example, there is an implication that the List api returns all results, rather than just the first page.

List the List network security rule operation retrieves all the routes in a route table.

But it doesn't retrieve all the routes. It returns the first page and then one can use ListNextResults to get the subsequent page(s). Also, the generated sentence doesn't really parse in English correctly.

The confusion worsens when one sees the ListAll and reads the description:

ListAll the list NetworkSecurityGroups returns all network security groups in a subscription

But it also doesn't "return all", but rather the first page and then one is expected to use ListAllNextResults to page through the results.

Go-autorest uses the swagger description to form documentation for the Go sdk. This documentation can be a bit misleading due to these descriptions.

"x-ms-generate-genericVersion": Generating a ListBySubscription() for services that do not have that.

All the services in Azure provide a mechanism to list all the resources in a resource group. Some services walk the extra mile to provide a mechanism to list all the resources in a subscriptions and that is awesome. However, some services do not and this can be problematic.

Until those services make it possible, it would be nice if the generated clients can fill that gap by generating a method that loops through all the resource groups to get the list of resources in a subscription.

This provides functional parity on the client side (The resulting function can be slower as it needs to make n+1 requests to get all the resources, where n is the number of resource groups).

The objective is to provide enough metadata to the generator so that it can generate the ListBySubscriptions() method. Whether this is done in parallel or a synchronous fashion is the prerogative of the Generator.

In any case this means that either every service will have to take a dependency on the resource management package or include the listing of resource groups as an operation in their swagger spec or all the runtimes can have this one method hand coded msRestAzure.resourceGroups.list().

This can be done in 2 possible ways. I like the second approach more over the first one. What do you guys think?

Mark the ListByResourceGroup() method with an extension:
"x-ms-generate-genericVersion": {"operationId": "ListBySubscriptions" }
This will indicate the generator to create a method named ListBySubscriptions() that will get the list of resourcegroups and list the resources within them.
Create a new operation named ListBySubscriptions under the already defined "x-ms-paths": {} extension

We can add two more extensions on it.
- Add "x-ms-generate-genericVersion" : true This extension will be a Boolean in this scenario. It is an indication that we need to ignore the path.
- Add "x-ms-operation-wrapper": { "WrappedOperationId": "List" }. This will still create the wrapper method for the generated ListBySubscriptions as described in #295 and we get all the benefits.

. . .
"paths": {
    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts": {
      "get": {
        "tags": [
          "StorageAccounts"
        ],
        "operationId": "StorageAccounts_ListByResourceGroup",
        "description": "Lists all the storage accounts available under the given resource group. Note that storage keys are not returned; use the ListKeys operation for this.",
        "parameters": [
          {
            "name": "resourceGroupName",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "The name of the resource group within the user's subscription."
          },
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "$ref": "#/parameters/SubscriptionIdParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/StorageAccountListResult"
            }
          }
        },
        "x-ms-pageable": {
          "nextLinkName": null
        },
        "x-ms-operation-grouping": {
          "methodName": "StorageAccounts_List"
        }
      }
    }
. . .
}
"x-m-paths": {
  "/genericListBySubscription": {
    "get": {
      "tags": [
        "StorageAccounts"
      ],
      "operationId": "StorageAccounts_ListBySubscription",
      "description": "Lists all the storage accounts available under the subscription. Note that storage keys are not returned; use the ListKeys operation for this.",
      "parameters": [
        {
          "$ref": "#/parameters/ApiVersionParameter"
        },
        {
          "$ref": "#/parameters/SubscriptionIdParameter"
        }
      ],
      "responses": {
        "200": {
          "description": "",
          "schema": {
            "$ref": "#/definitions/StorageAccountListResult"
          }
        }
      },
      "x-ms-pageable": {
        "nextLinkName": null
      },
>>>> "x-ms-generate-genericVersion": true,
>>>> "x-ms-operation-wrapper": {
          "WrappedOperationId": "StorageAccounts_List"
       }
    }
  }
}

Naming of DiskEncryptionSettings properties

Currently VM's disk encryption settings is defined as below:

"DiskEncryptionSettings": {
      "properties": {
        "diskEncryptionKey": {
          "$ref": "#/definitions/KeyVaultSecretReference",
          ...
        },
        "keyEncryptionKey": {
          "$ref": "#/definitions/KeyVaultKeyReference",
          ...
        },
        ...
      },
      "description": "Describes a Encryption Settings for a Disk"
}

DiskEncryptionSettings:

The naming of properties are bit confusing - diskEncryptionKey, keyEncryptionKey. names such as keyVaultSecretReference and keyVaultKeyReference will be better. Similar to imageReference

I know we cannot introduce breaking changes in server, but we could use x-ms-client-name so that atleast generated code will have better variable name.

@huangpf @devigned @amarzavery

	"enum": [
	"Basic_A0",
	"Basic_A1",
	"Basic_A2",
	"Basic_A3",
	"Basic_A4",
	"Standard_A0",
	"Standard_A1",
	"Standard_A2",
	"Standard_A3",
	"Standard_A4",
	"Standard_A5",
	"Standard_A6",
	"Standard_A7",
	"Standard_A8",
	"Standard_A9",
	"Standard_G1",
	"Standard_G2",
	"Standard_G3",
	"Standard_G4",
	"Standard_G5"
	],

	"CheckNameAvailabilityResult": {
	"properties": {
	"nameAvailable": {
	"type": "boolean",
	"description": "Gets a boolean value that indicates whether the name is available for you to use. If true, the name is available. If false, the name has already been taken or invalid and cannot be used."
	},

azure / azure-rest-api-specs Goto Github PK

azure-rest-api-specs's Introduction

Azure REST API Specifications

Description

Getting started

Terminology

Directory Structure

Next steps

azure-rest-api-specs's People

Contributors

Stargazers

Watchers

Forkers

azure-rest-api-specs's Issues

Ambiguous Permissions on Properties Complicate 75+ Create-OR-Update Operations

Reference - today, there are 75+ such Create-OR-Update operations with such ambiguous permissions on properties

Service Fabric Swagger Spec Does Not Define Errors

One More Thing ...

There are 92 other variations of list names

Missing Error Definitions or References in 9 Swagger Specs

Security Error Channeled Through HTTP 200

Delete Redis Cache Returns Abnormal 404

Inconsistent list operations across Azure Swagger specifications

list() and listAll() used interchangeably with the same semantics

list(string) and listByResourceGroup(string) are used interchangeably with the same semantics

listAll() is missing where developers would expect them

Complicated list() names with complex parameters

Recommend Projects

Recommend Topics

Recommend Org

`list()` and `listAll()` used interchangeably with the same semantics

`list(string)` and `listByResourceGroup(string)` are used interchangeably with the same semantics

`listAll()` is missing where developers would expect them

Complicated `list()` names with complex parameters