Who needs documentation?

While working on a solution that is supposed to list Azure Resources using client side code, I came into contact with Azure Resource Manager REST API. And honestly this is a pretty awesome collection of API’s! Now the whole issue with this API is that it is actually a constantly changing collection of API’s and that there is no documentation available at all. How useful is that?

Sure they’ve written an article with the title “Azure Resource Manager REST API Reference”, but it contains high level information only. They actually tell you that the best way you can find out what will be returned by the API, is by using a tool they call Azure Resource Explorer.

The first issue I have with that, is that you can only execute calls on resources that you’ve got in your Azure Subscription. So if you would like to find out what response will be returned when you request information on a Storage Resource, you will first have to create such a resource in your Azure Subscription. You can then use the Azure Resource Explorer, to see the JSON result returned. This will tell you nothing of course about the actual schema that you can expect.

The second issue I have with that, is that I have no way of creating a decent client side proxy with something like T4 templating. So it took me a couple of weeks to create a client side proxy to get only the basic information and it’s all based on guessing. Good job Microsoft!

Did nobody at Microsoft every heard about something like Swagger?

UPDATE:
Microsoft did hear about Swagger! Their own PowerApps product can connect to custom API’s as long as you can provide the definition file in… Swagger format! But wait. “Does that mean that I cannot connect to Microsoft’s own Graph API to fetch person details into my PowerApp unless I create the Swagger definition file manually?” Yes… sigh.

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.