azure-sdk-for-net icon indicating copy to clipboard operation
azure-sdk-for-net copied to clipboard

Published 20 hours ago • verified publisher icon Azure

Documentation for apiVersion parameter

Open stmax82 opened this issue 4 years ago • 12 comments

Some methods require the "apiVersion" parameter. Could you please provide some more documentation on why this parameter is required and how to obtain a list of valid values?

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

stmax82 avatar Jan 19 '21 08:01 stmax82

Thank you for your feedback. Tagging and routing to the team member best able to assist.

jsquire avatar Jan 19 '21 14:01 jsquire

@stmax82 what methods in particular? These may mean different things depending on the API.

bquantump avatar Jan 20 '21 16:01 bquantump

@bquantump see link above or screenshot below. Some methods take an "apiVersion" parameter without explaining what it is.

image

stmax82 avatar Jan 20 '21 16:01 stmax82

@stmax82 in this case it is going to be the API version for the resource you want to delete. For example, if the resource is a VM then you need to give it one of the valid api-version for VM. The latest is "2019-07-01" for vm for example.

You can find api version in the docs https://docs.microsoft.com/en-us/rest/api/azure/

We can also update this docs in future releases

bquantump avatar Jan 20 '21 17:01 bquantump

The link https://docs.microsoft.com/en-us/rest/api/azure/ doesn't really explain what the valid values for the apiVersion parameter are? Not sure where you found "2019-07-01" for VMs? It's not in the provided link.

As you can see, it's quite hard for users to figure out the right value that should be passed to the apiVersion parameter.

I am for example trying to delete a Workbook resource. Where do I find the correct value for the apiVersion parameter?

The docs should provide examples or references to other pages that contain lists of valid apiVersions per resource type.

stmax82 avatar Jan 20 '21 17:01 stmax82

image

bquantump avatar Jan 20 '21 18:01 bquantump

This will show the latest version that is RELEASED. You can find older version and all version here for compute as an example:

https://github.com/Azure/azure-rest-api-specs/tree/master/specification/compute/resource-manager/Microsoft.Compute/stable

bquantump avatar Jan 20 '21 18:01 bquantump

Is it a Azure Monitor Workbook resource you are trying to delete?

bquantump avatar Jan 20 '21 18:01 bquantump

@bquantump I think so, yes.. it was an Azure Monitor Workbook that was exported as ARM template and re-imported with workbookType = tsg (Techsupport Guide). But I'm not sure if this matters.. the apiVersion parameter needs better documentation that can be used to lookup the correct value for any resource type.

stmax82 avatar Jan 26 '21 12:01 stmax82

@Arm team. I think we can update the description of API version to include links to Azure Rest API reference for user to locate the current version.

allenjzhang avatar Jan 26 '21 19:01 allenjzhang

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @armleads-azure.

Issue Details

Some methods require the "apiVersion" parameter. Could you please provide some more documentation on why this parameter is required and how to obtain a list of valid values?

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

Author: stmax82
Assignees: bquantump
Labels:

ARM, Docs, Mgmt, Service Attention, customer-reported, feature-request, needs-team-attention
Milestone: Backlog

ghost avatar Jan 26 '21 19:01 ghost

@xboxeer please help to follow this issue

ArthurMa1978 avatar Jan 10 '23 05:01 ArthurMa1978