Azure REST API Guidelines Update

Updated Guidelines

The Azure API team has released a major update to the Microsoft Azure REST API Guidelines. The updated guidelines have been extended and clarified to drive greater consistency across the entire portfolio of Azure service APIs. This consistency benefits customers that access Azure services directly through the REST APIs. The consistency also benefits users of the Azure SDKs and Azure CLI. The SDKs and CLI are based on the REST APIs, and in some cases are generated from the API definition. The presentation has also been revised to use a consistent format with the Azure SDK guidelines.

Considerations for Service Design

There’s also a new “Considerations for Service Design” document, intended for teams designing new services. The document describes the general approach to API design for cloud services. Much of the new document applies to cloud-based APIs. The specific protocol of the API doesn’t matter, as the guidelines can be applied beyond HTTP-based REST APIs.

Summary

The primary focus of the REST API guidelines is Azure services. However, the guidelines can also serve as a reference when designing any REST API, particularly for cloud-based applications and services. To learn about key elements of the Azure API guidelines, see Designing & Versioning HTTP/REST APIs.

Whether you’re updating an existing API or creating a new one, the revised guidelines will help you:

Create a more durable API.
Accelerate your development.
Yield cleaner, more consistent SDKs.

For example, the guidelines help you understand when to use PATCH vs. POST. You’ll also understand why the HTTP action verb selection is an important decision that impacts your service design. In short, you’ll be creating a delightful developer experience. Review these documents as you build out your Azure service. If you have any questions, don’t hesitate to reach out to the API Stewardship team. Check out the Azure REST API Guidelines today.

Azure SDK Releases

Azure SDK Blog Contributions

Thanks for reading this Azure SDK blog post. We hope you learned something new, and we welcome you to share the post. We’re open to Azure SDK blog contributions from our readers. To get started, contact us at azsdkblog@microsoft.com with your idea, and we’ll set you up as a guest blogger.