Our journey on building the Go SDK for Azure

Posted on 26 January, 2017

Program Manager

Over the last few months, we've been busy adding new functionality to the Azure Go SDK and we'll keep doing so as we march towards public preview next year.

If you followed the recent changes on our GitHub repo, you probably noticed few general improvements we made to the SDK

Model Flattening

In the last release we added model flattening to many of our APIs (i.e. you can type Resource.Sku.Family instead of resource.Properties.Sku.Family), which makes for more readable code.

Better error messages during parameter validation

During parameter validation, we enabled the SDK to return an error with the info needed to fix the JSON before sending the request out - making it easier to identify/correct potential coding mistakes.

For example, let us take a scenario where a user wants to create a resource group and location is required in that operation. User forgets to include it in the request.

In previous SDK versions, the operation would fail inside Azure and user would get the following error

resources.GroupsClient#CreateOrUpdate: Failure responding to request: StatusCode=400 -- Original Error: autorest/azure: Service returned an error. Status=400 Code="LocationRequired" Message="The location property is required for this definition." 

In the latest SDK version, user would get

resources.GroupsClient#CreateOrUpdate: Invalid input: autorest/validation: validation failed: parameter=parameters.Location constraint=Null value=(*string)(nil) details: value can not be null; required parameter 

 

We also improved the coverage and functionality of the data plane of the SDK by adding support for file and directory manipulation, getting/setting ACLs on containers, working with the Storage Emulator and other various storage blob and queues operations.

Some of the fixes and improvements added to the SDK have been provided by enthusiastic developers outside of our Microsoft team and we would like to extend our sincere gratitude and appreciation to everyone who sent us feedback and/or pull requests. We took note of your requests for better API coverage in the data plane, better documentation, release notes and samples, and we are making progress in incorporating them into our future releases.

Breaking changes

Speaking of future releases: while many API changes are expected to be additive in nature, some of the changes we are introducing will break existing clients. A recent example was issue 1559, which arose when we added parameter validation; in the near future, some methods and parameters may be added/deleted, parameters change order, and structs can change while we are considering model flattening on more APIs. This is part of the reason why we keep the 'beta' label on the Go SDK, and we are carefully examining every proposed change for alternatives that will not break the existing functionality.

We’d like to thank in advance all of you who continue to use our Go SDK and send us feedback; we are committed to building the best experience for developers on our platform, and we'd like to make sure the changes have minimal impact on your development cycle as the SDK goes towards more mature stages of public preview and GA (general availability)

We will use this blog to keep you updated on the progress and potential breaking changes, and we’ll give you a heads-up as we are approaching new milestones.
Have any suggestions for how to make the SDK better? We’d love to hear from you! Send us a pr or file an issue, and let’s talk!