We expect all Azure client libraries to go through rigorous APIs reviews similar to those conducted for any other API produced by Microsoft (for example, the .NET APIs). It’s critical that the review is conducted early enough to allow time for fixes, and sometimes significant API redesign based on the review feedback. If you have never participated in an Azure client library API review, we recommend that you schedule a pre-review (consulting session) before you start working on the APIs.
How to Design Great Azure APIs
Make sure your client libraries follow Azure SDK Design Guidelines. You can find language-specific guidance as follows:
What to Prepare for a Review
To conduct a review, we need the following things from the owners of the client library:
- Several code samples showing how the client library is meant to be used by customers. An example of a good set of usage samples can be found here.
- A listing of 3-5 champion scenarios relevant to the developer. These must identify the critical scenarios that the majority of developers will experience. For each champion scenario, a link to a code sample in the repo must be provided. It is expected that these champion scenarios are optimized for, ensuring succinct, intuitive, and productive developer experiences are possible for each.
- Listing of the APIs. See below for example and tools to generate it.
- Link to the service documentation/specification.
- Link to the service REST APIs, if applicable/available.
- If the client library is already prototyped, the proposed distribution (for example, DLL files for .NET, or JAR files for Java)
- If the client library already GAed in the past, and this review is for additional APIs, the diff between the old API and new API.
During API reviews, we look at API usage samples (as discussed above) and a detailed API listing. You can see an example of such listing here.
If you have a prototype of your APIs, depending on the language the APIs are for, you can possibly generate the API listing.
- If the API is a .NET APIs, use API Reviewer Tool
- If the API is a Python API, use reference documentation generated by Sphinx.
d.tsfile for your client library. Use API-Extractor to produce a single file with your entire API surface area. Note that API-Extractor does not need to complete without error in order to produce the rollup
- If the API is a Java API, use your preferred build tool to generate a JavaDoc output (e.g.
mvn javadoc:javadocwith Maven), and zip up the output.
- For all other languages, send a request to the Architecture Board to discuss the best format on individual basis.
API Review Lifecycle
To request a review:
- Submit an issue. If the service is pre-release, use the private repository. For escalations, email the Architecture Board only after submitting the issue.
- Ensure you provide all information (or direct links to the information) for ease of review.
- The ADP Review Board PM will schedule a 1:1 with a language architect to provide initial guidance. It is important that this initial review happen BEFORE any major development happens.
- Get the ADP Reviews happening in concert with your design process for best results.
- If needed, a review with the entire review board will be scheduled. The cases where this is necessary include:
- This is a completely new client library.
- The reviewing language architect feels there are cross-cutting concerns.
- Exceptions from the guidelines are being sought (such as additional dependencies)
- After reviews are completed, the review team will publish recommendations.
It is normal to have multiple API reviews as the development of the client library progresses.