A first look at the new Azure SDKs

If you’re building applications that work against Azure services, it’s likely you’re using one or more of Microsoft’s published SDKs. It’s an approach that makes sense, saves time, and keeps code under control. That’s because working directly against a Representational State Transfer API can be complex, as you have to construct the appropriate queries and parse the response JavaScript Object Notation.

Using an SDK that’s tailored to whatever language you’re using simplifies the process considerably, turning calls into methods and responses into objects. There’s no need to translate data formats or build complex query strings, reducing the risk of error. Microsoft has provided SDKs for Azure since the earliest days of its public cloud, adding new features to its libraries as they roll out.

That long history and Azure’s rapid growth has left the current set of SDKs somewhat out of phase with the way we build modern applications. While they work well enough, they’re not as easy to mix with current design thinking and don’t fit perfectly with the patterns and practices that are used in modern enterprise application development. When you’re launching a new service and getting it built into applications you must be fast. You don’t have time to sit down with the teams working on other SDKs for other aspects of the service and make your approaches consistent or understand how exactly your SDKs are being used.

Mature Azure services need mature SDKs

Azure’s core services are approaching maturity. They underpin applications both inside Microsoft and across the wider world. With a slower development cadence in Azure, there’s now time to rework the supporting SDKs and to build a new common and consistent way of working with Azure. The first fruits of that reworking have now arrived: preview SDKs for Azure Storage, Azure Cosmos DB, Azure Key Vault, and Azure Event Hubs.

The new SDKs are shipping as libraries for Python, Java, JavaScript, and .Net, the most common languages used on Azure. They build on a set of common standards for library design and development, based on developer-focused principles. The initial blog post from Microsoft defines these principles as:

1. Create easy-to-use APIs with productivity on par with the best libraries of the language ecosystems.
2. Provide APIs that are idiomatic to the language and ecosystem they are used in.
3. Evolve over time in a very compatible fashion.
4. Focus as much on documentation and samples as on APIs.

They’re sensible rules. The first two require Microsoft to understand the ways developers use languages, and the reasons why those languages are being used. If the Azure SDKs don’t fit with the many ways that developers use languages, then they’re not going to be used. Modern development methodologies and languages are opinionated, defining how code is structured and styled. Any SDK from any service must fit into those structures and styles. Azure needs to fit in with the resulting development approaches.

Microsoft’s developer-first approach 

From a developer point of view that last principle is important; good documentation is key to good applications. You need to look at API-first companies such as Twilio to see how SDKs and documentation go hand in hand. Twilio’s build process won’t push a new API or SDK to production without documentation and code samples.

Microsoft appears to have taken these principles to heart with its new SDK releases. They’re being developed in the open, in a common GitHub repository tree. It’s here that Microsoft is publishing its overall design guidelines, alongside specific implementations and guidelines for the currently supported languages, with an additional set of Go SDKs being developed alongside the four main languages.

As the SDKs are open source, Microsoft accepts contributions, though you will need to agree to a Contributor License Agreement before making any pull requests. You should only need to do this once, as it covers all the public Azure GitHub repositories.

Inside the new Azure SDKs

It’s worth looking at the new SDKs in more detail, as they’re a complete rewrite of the libraries you’re already using. Each language will initially have a different set of services. They all support the core set of services, but some, like the .Net and Java SDKs, add support for others including Azure’s Identity services.

The .Net SDK is a series of NuGet packages containing the libraries needed to work with Azure services, which keeps code bloat to a minimum. If you’re using Azure Storage, you need to install the appropriate Storage package, with separate packages for Blobs, Queues, and Files. For example, if you’re writing code that’s intended to work with a Blob, start by adding an Azure Storage Account to your subscription, using the Portal or the Azure CLI. You can then install the client library on your development system, using the dotnet add package command.

Once downloaded and added to your project, you can add the appropriate using statements in your code, and then use the library methods to set up a connection to a Blob container and to a specific file, where you can use simple upload and download methods to interact with Azure Storage. The APIs used in the SDK support both synchronous and asynchronous operations, with specific versions of the key methods.

The documentation in the GitHub repositories for each SDK is clear and easy to read, with sample code and links to the Azure SDK documentation. Much of the documentation is automatically generated, but you should find it enough for most development tasks, along with sample source code and any readme files.

The repositories for other development platforms are similar, with libraries loaded into the appropriate repositories and ready for use in your code. That means using pip with Python, maven with Java, and npm with JavaScript. You can build the SDKs into your existing development tools and processes without having to change anything.

It’s still early days for the new Azure SDKs, but a first look shows a lot of promise. They’re easy to understand and fit well with language best practices: a .Net library behaves like .Net; a JavaScript library behaves like JavaScript. The result is code that’s easier to read, easier to understand, and above all, easier to debug. If you’re willing to risk preview code, it’s worth exploring how you can update your apps with the new libraries. If not, it won’t be too long before they’re released and you can start using them in your code.