Azure SDK Client Library Review: Championing User Experience

by Alex Johnson 61 views

Welcome! This document outlines the process for reviewing your Azure client library, ensuring it aligns with best practices and provides a seamless experience for developers. Let's dive in and make sure your library shines! Remember, a well-crafted client library is key to a positive developer experience when interacting with Azure services.

Important Updates for Internal Teams

For internal teams, scheduling review sessions with the Azure SDK Architecture team has changed. Please use the Scheduling Tool for both Introduction and SDK Review meetings. This streamlined approach ensures a more efficient review process for everyone involved.

Thank you for initiating the process for your Azure service client library! A thorough review ensures that your APIs align with Azure guidelines and provides developers with a consistently excellent experience. This review is a critical step in delivering high-quality SDKs.

The Architecture Board reviews only Track 2 libraries. If your library does not meet this requirement, please contact the Architecture Board before submitting your review request. Make sure your library is compliant before starting the review process.

Please refer to our review process guidelines to understand the requirements of this template. It's designed to guide you through the process and ensure a comprehensive review.

Before submitting, accurately adjust the title of the issue. A clear and concise title will help reviewers quickly understand the purpose of your submission. This saves time and ensures a faster review process.

Remember to include all required materials before scheduling a meeting. Complete and accurate information is crucial for a productive review.

Contacts and Timeline

This section helps us understand the context of your library's development. Please provide the following information:

  • Service team responsible for the client library: (e.g., Azure Blob Storage team)
  • Main contacts: (Names and contact information)
  • Expected stable release date for this library: (e.g., Q3 2024)

About the Service

Provide essential background information about the service your client library interacts with:

  • Link to documentation introducing/describing the service: (e.g., Azure Blob Storage documentation)
  • Link to the service REST APIs: (e.g., Azure Blob Storage REST API documentation)
  • Is the goal to release a Public Preview, Private Preview, or GA? (Specify the release stage)

About the Client Library

This section focuses on the details of your client library:

  • Name of client library: (e.g., azure-storage-blob)
  • Link to library reference documentation: (e.g., https://learn.microsoft.com/en-us/javascript/api/@azure/storage-blob/?view=azure-node-latest)
  • Is there an existing SDK library? If yes, provide the link to the existing library. (e.g., https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob)

Step 1: Champion Scenarios

Champion scenarios are at the heart of the review process. They provide a practical understanding of how developers will use your library in real-world applications. By focusing on common use cases, we can ensure your library is intuitive and easy to adopt. These scenarios should highlight the key functionalities and the overall developer experience. Think about the common tasks developers will perform with your service and build scenarios around them.

Here's how to approach champion scenarios. They are designed to show the value of your client library and how easy it is to use.

  1. What is the app the developer is building that uses your client library? Describe the application. What is it designed to do? (e.g., A web application that uploads and manages images in Azure Blob Storage.)
  2. Who is the end-user of the application (the developer's customer)? Describe who will be using the application. (e.g., Content creators, website administrators, or anyone needing to store and manage media files.)
  3. What features of the API need to be explained in the sample so that someone could use this API in a real app? Focus on essential API features to demonstrate functionality. (e.g., Uploading a file, listing blobs, downloading a file, and deleting a blob.)
  4. How does the authentication workflow look? Explain the steps to authenticate and authorize the client library. (e.g., Using a connection string, managed identity, or Azure Active Directory.) Ensure the authentication process is straightforward and secure.

Refer to the Champion Scenario section here for more guidance. The champion scenarios should clearly illustrate the value proposition of your library, making it easy for developers to understand and adopt. Code samples are great, but even pseudocode can effectively convey the intent and steps involved.

Provide the following for each champion scenario:

  • Champion scenario 1
    • Link to library’s sample folder:
  • Champion scenario 2
    • Link to library’s sample folder:
  • …
  • Champion scenario n
    • Link to library’s sample folder:

Step 2: Quickstart Samples (Optional)

Quickstart samples provide a hands-on way for developers to quickly understand and use your library. These samples should cover the most common operations developers will perform with your service. The easier it is for developers to get started, the more likely they are to adopt your library. These samples should be clear, concise, and easy to follow. They should cover a range of scenarios to show off the capabilities of your library.

Include samples demonstrating how to consume the client library if available:

  • Create a new resource
  • Read the resource
  • Modify the resource
  • Delete the resource
  • Error handling
  • Handling race conditions/concurrency issues

Review Focus: Authentication

Authentication is a crucial aspect of using any Azure client library. This is the starting point for developers and requires a secure, easy to use process. The authentication workflow must be easy to understand and implement in the application. This ensures that only authorized users can access the service. It is very important to include the authentication workflow in the champion scenarios and any associated samples. Provide clear instructions on how to authenticate, including the use of connection strings, managed identities, and Azure Active Directory. The overall goal is to make the process as seamless as possible while maintaining security.

Conclusion

This guide ensures a smooth review process and a robust client library. By completing these steps, you're contributing to a great developer experience. We look forward to reviewing your library and helping you create a valuable resource for developers using your Azure service. Remember, a well-designed client library is a key factor in the adoption of your service. Make sure to carefully consider all the points in this guide to optimize the user experience. Thank you for your hard work and dedication to providing the best possible developer experience with your Azure service!

For more in-depth information on the Azure SDK, check out the official documentation on the Azure SDK Design Guidelines.