Azure-cli: Relation between REST API endpoint, Azure CLI command and SDK method

[ferenczy]

It would be very useful to add and display relations to various logically related documentation pages. It would allow a possibility to switch for example between the same feature (represented by a REST API endpoint) accessed using various methods. The feature may be for example "list key vaults by a subscription" and the method may be a REST API endpoint, an SDK method or for example an Azure CLI command.

Problem

Note: this is not issue of the Azure CLI documentation specifically, this issue should be created one level above as it addresses multiple Azure documentation projects and the goal is to link various documentation projects together (Azure CLI, SDKs, CLI, etc.) using page relations.

I'll try to explain it in more detail: let's say I'm interested in the mentioned "list key vaults by a subscription" feature. My usual workflow is that:

1. First, I want to do some quick testing that such feature/API endpoint matches my needs, so I'll use Azure CLI to test it. But what's the right command? It takes quite significant time to find what exact CLI command matches the feature I'm interested in. I guess it's az keyvault list.

2. Good, so I have done quick testing using the CLI and it's exactly what I need so now, I'm going to automate it using a Python script and Azure SDK for Python. Once again, I have to find the matching SDK method to call the same REST API endpoint and get the same data. In case of SDKs it's even more complicated to go through a type hierarchy and locate the right method. A lot of wasted time to find VaultOperations.list_by_subscription method.

3. Repeat such workflow several times for various features and a sum of the wasted time becomes quite significant.

I hope it's clear now. That's my problem.

Solution

Technically: add a relation between matching documentation pages, e.g. for the "list key vault by subscription" feature it would be:

• REST API endpoint list key vaults by subscriptions
• Azure CLI command az keyvault list
• Python SDK method VaultOperations.list_by_subscription method
• .NET SDK method ...
• ...

UX: every documentation page with any relations defined would contain a list of related pages.

[tjprescott]

@sptramer for where this issue should live.

[tjprescott]

@ferenczy it isn't as simple as it sounds because there often isn't a 1-to-1 mapping between an API endpoint, a CLI command and Powershell command. A CLI command might call several endpoints for instance. I'm adding the "closing-soon" tag because this isn't a CLI-specific issue and should live here, but we will ensure it ends up in the appropriate location.

[sptramer]

@tjprescott No idea where this should live - site engineering maybe? It's an improvement related to our cross-linking for docs with reference and possibly within service verticals. I'd tag in @rloutlaw or @dend to see what they think about this proposal.

[tjprescott]

@rloutlaw @dend we will be closing this issue by the end of December since it isn't a CLI product issue. Can you help us route it to the appropriate team?

[rloutlaw]

@tjprescott @dend @sptramer This lack of interconnected-ness is something that I am hoping to resolve in the future-but it's very much something we have to sort out through autogeneration, and has a scope wider than just the CLI.

@dend Can we get this issue added to our feature backlog?

[tjprescott]

Hi @ferenczy thank you for your suggestion. This has been accepted onto the docs team's backlog for triage. Since there's nothing actionable from the CLI team, I will close this issue.

[ferenczy]

Thank you guys. The autogeneration would be great but as @tjprescott wrote, there's no 1-1 mapping between the access methods (REST API, SDK, etc.) so maybe it will need some manual referencing (as a document metadata).

Anyway, I think you got my point, from a user perspective, I just need to be able to easily switch between various access methods of the same Azure resource where access method is for example a REST API endpoint, SDK method or PowerShell cmdlet and Azure resource is for example "get list of key vaults in a subscription" or "create new virtual machine".

I'll leave the technical solution up to you :)

Could you just link the migrated ticket here, so I can follow it, please?

[tjprescott]

https://ceapex.visualstudio.com/Engineering/_workitems/edit/55439

I'm not sure you will be able to see it as it may be an internal ticket.