Previewing Azure SDKs following new Azure SDK API Standards
Why are we doing this?
Much like moving software from the client or on-premises to the cloud is a paradigm shift, we too have been going through a period of rapid innovation in Azure’s capabilities and learning about how best to expose it to developers. Now that some Azure services have matured and been adopted into business-critical enterprise applications, we have been learning what patterns and practices were critical to developer productivity around these services. In addition, we’ve been listening to your feedback and we’ve made sure that our new effort has incorporated your suggestions and requests. Finally, we understand that consistency, ease of use, and discoverability are equally important to the identified patterns when it comes to working with the Azure SDKs.
The team will go into much of what I am about to outline in follow-up blog posts but to get started, the big changes came from a set of objectives we defined based on your feedback. Those were:
- Create easy to use APIs with productivity on par with the best libraries of the language ecosystems.
- Provide APIs that are idiomatic to the language and ecosystem they are used in.
- Evolve over time in a very compatible fashion.
- Focus as much on documentation and samples, as on APIs.
- Change how we create the libraries at their core.
Ease of use and productivity
Productivity is a multifaceted topic on its own, but two main elements of it are consistency and usability.
To help drive usability, we tweaked how we gather user feedback. We continue to do many of the standard practices in the industry such as releasing previews, working directly with developers on their projects, and responding to issues in many different community forums but the next step for us was to usability test the libraries. For each of the libraries we are releasing today, we have brought developers into a lab and had them work through different use cases while we observed them. That feedback was instrumental to shape both the guidelines as well as the API shape of the libraries.
Compatibility has always been a value at Microsoft. Developers put significant time and money into solutions and should be able to count on them continuing to work. There is a tension here. For some cases we have had to make breaking changes to get to a better foundation. We believe aligning on that foundation will help meet the productivity goals outlined above, and once it’s set we intend to provide a high degree of compatibility. As a final note on compatibility, we’ve looked at the dependencies that we took and tried to minimize them as much as possible to reduce future incompatibilities and versioning complexities which should make upgrading libraries and using other pieces of software alongside these libraries easier.
Having good documentation and samples could be considered an aspect of productivity but we wanted to call it out as its own goal because many developers rate it as the top factor in choosing what technologies to use. Much like the usability studies we’re doing on the APIs themselves, we have been doing the same on Azure Quickstarts to ensure that new developers can begin to experiment with Azure Services quickly. We have also heard feedback that both API Reference code snippets and samples get out-of-date and we have been building the tooling to build API Reference code snippets and samples regularly from GitHub and publish those into documentation.
Change how we build
We also found we needed to change how we work with and engage the community and what we build on top of. To that end, we’ve begun work to restructure and centralize our development effort into a few key repositories:
- Azure-sdk: As a central location to start from and a place for high level topics like the design guidelines.
- Repositories for each language:
Finally, we built a new core library that is helping us provide common features like identity and authentication, both synchronous and asynchronous APIs, logging, error handling, networking retries and more across all libraries.
What should I do?
We are very pleased to be sharing the preview release of the new Azure libraries that conform to many of the principles outlined above. We would like to encourage you to download and try the new SDKs today. To help you along the way, we are providing release notes describing what’s new in each library, how to get the packages, and how to file GitHub issues specific to the previews.
In addition to filing GitHub issues, feel free to also follow and tweet us @AzureSDK. We look forward to receiving your feedback so we can improve the libraries, and make it easier for you to create great software and solve problems with Azure.