‹ Reports
The Dispatch

OSS Report: Azure/azure-rest-api-specs

Azure REST API Specifications Face Persistent Documentation and Implementation Discrepancies Amid Active Development

The Azure REST API Specifications project, a key resource for developers working with Microsoft Azure, is experiencing ongoing challenges with discrepancies between API documentation and actual service behavior, despite active community and developer engagement.

Recent activities in the project highlight a significant focus on addressing bugs related to API behavior inconsistencies, particularly around identity properties and resource configurations. The development team has been actively involved in updating API versions and resolving issues, with notable contributions from members like Yuchao Yan, Abhay Pratap, and Mike Harder. The repository continues to see robust activity with numerous pull requests aimed at introducing new features and improving documentation.

Recent Activity

Recent issues and pull requests reflect a concerted effort to align API specifications with actual service behaviors. Issues such as #30419 and #30411 indicate ongoing challenges with API usability and clarity, while pull requests like #30435 and #30433 focus on introducing new features and enhancing existing capabilities.

Development Team and Recent Activity

  1. Yuchao Yan

    • Updated tspconfig.yaml for Python (3 days ago).
    • Fixed issues in various specifications (5 days ago).

  2. Abhay Pratap

    • Resolved subscription operation issues (6 days ago).
    • Co-authored updates to the Microsoft.Subscription API (7 days ago).

  3. Mike Harder

    • Engaged in dependency upgrades (8 days ago).
    • Merged branches for maintenance (9 days ago).

  4. Priyankarking

    • Updated Redis Enterprise API specifications (10 days ago).

  5. Jaskirat Singh

    • Focused on SAP Virtual Instance management updates (11 days ago).

  6. Alfredo Santamaria

    • Contributed to Service Fabric Managed Clusters updates (12 days ago).

  7. Badea Marjieh

    • Fixed TypeSpec issues in Fabric management specifications (13 days ago).

  8. Ramneet Tung

    • Added a new event type to Call Automation API (14 days ago).

  9. Samir Solanki

    • Merged branches related to Azure API Management (15 days ago).

  10. Chenxi Jiang

    • Updated Python configurations across services (16 days ago).

Of Note

Quantified Reports

Quantify Issues



Recent GitHub Issues Activity

Timespan Opened Closed Comments Labeled Milestones
7 Days 10 3 7 1 1
30 Days 31 9 38 1 1
90 Days 94 36 172 13 1
1 Year 359 181 650 65 1
All Time 3418 1780 - - -

Like all software activity quantification, these numbers are imperfect but sometimes useful. Comments, Labels, and Milestones refer to those issues opened in the timespan in question.

Quantify commits



Quantified Commit Activity Over 30 Days

Developer Avatar Branches PRs Commits Files Changes
Yuan Zhuang 1 1/0/0 4 195 84078
Samir Solanki (solankisamir) 2 2/0/1 6 301 82373
YunsongB 1 0/0/0 1 194 40866
Jaskirat Singh 1 3/2/1 2 194 39207
Travis Wilson 2 1/0/0 6 216 30943
Bryan Strassner 1 0/0/0 1 137 27992
ZianWang02 1 0/0/0 1 143 25630
jonathanserbent 1 0/0/0 1 53 24409
hmmorales 1 3/3/0 1 132 23111
FumingZhang 2 2/1/0 2 114 22563
Paul Hsu 1 0/0/0 1 73 22030
wiboris 1 0/0/0 1 102 21610
Davide Montanari (davidemontanari) 1 1/0/0 8 115 18000
None (tbyfield) 1 1/0/1 3 153 17711
Auðunn 1 2/0/0 1 97 16006
vrusheshp 1 1/1/0 1 147 13837
Rena 1 0/0/0 1 85 12707
pednekarpraj 1 0/0/0 1 105 12596
Alfredo Santamaria 1 0/0/0 1 68 11921
Sneha Nagendra 1 1/0/0 1 121 11156
mpothuganti 2 3/2/1 9 62 10658
Oliver Towers 1 0/0/0 2 115 10600
Jorge Cotillo 1 0/0/0 1 40 9703
yaotongms 1 0/0/0 1 56 8864
Sean McCullough 1 4/0/0 1 2 7636
sssharma24 1 1/0/0 1 53 7376
Srinivas Alluri 1 0/0/0 3 46 7152
Ashwin Jeyaseelan 1 0/0/0 2 64 6602
None (DevBaburaj) 1 1/0/0 24 43 6301
Bidisha Chakraborty 1 0/0/0 1 14 6262
None (sofiya09) 2 2/0/1 8 58 6171
Sayeed Alam 1 0/0/0 2 66 5678
curiekim00 1 0/0/0 1 41 5466
ronf11 1 0/0/0 1 20 5187
emmeliaAra 1 0/0/0 1 34 4300
fangru2023 2 1/0/0 3 41 3870
priyankarking 1 2/1/1 1 35 3862
None (ramoka178) 1 2/0/1 6 31 3437
Mike Harder 1 14/9/4 11 18 3338
Han Chiang 1 3/2/0 4 10 3049
Nneka Okeke 1 0/0/0 6 66 2905
None (glorialimicrosoft) 1 1/0/0 24 22 2810
Zao Wang 1 0/0/0 1 19 2738
wangyuantao 1 0/0/0 1 13 2633
Ryan Zhang 1 0/0/0 1 21 2434
bowgong 1 0/0/0 1 31 2310
Jiri Burant (jiriburant) 1 1/0/0 11 15 2180
Abhay Pratap 1 1/1/0 2 23 1987
HaiyiWen 1 0/0/0 1 20 1895
Shreya Anand 1 1/1/0 1 28 1846
McCoy Patiño (mccoyp) 1 1/0/0 6 5 1621
zhifzhan 1 0/0/0 1 9 1143
annegeorge17 1 0/0/0 1 14 1126
us6193 1 0/0/0 1 11 962
Arthur Ma 1 1/1/0 2 29 953
Timothee Guerin 1 1/1/0 2 33 630
Nate Kimball 1 0/0/0 1 6 548
Brent Rusinow (brrusino) 1 1/0/0 3 3 446
skadhiresan 1 0/0/0 1 6 422
Vu Tran 1 0/0/0 1 4 376
Krista Pratico (kristapratico) 1 1/0/0 20 1 281
Yuchao Yan 3 10/7/3 14 15 247
dhananjay824 1 0/0/0 1 13 226
ZiWei Chen 2 5/1/2 4 7 180
Jingshu918 1 1/1/0 2 6 174
Libba Lawrence 1 1/1/0 1 4 164
Andres Borja 1 0/0/0 1 4 132
Gerardo Lecaros (glecaros) 1 1/0/0 3 5 107
papadeltasierra 1 1/1/0 1 3 102
Badea Marjieh 1 2/2/0 3 8 83
Tal Shoham 1 1/1/0 2 3 80
Quentin Robinson 1 0/0/0 2 1 70
Wenming Liu 1 0/0/0 1 5 66
Aurgho Bhattacharjee 1 2/1/0 1 1 56
Pranshu Bansal (PranshuBansalDev) 1 1/0/0 1 1 54
Chinonso Chukwuogor 1 4/2/0 1 3 51
Wei Hu 1 2/2/0 2 1 46
Josh Harrington 1 3/2/1 3 2 45
ChenxiJiang333 1 2/1/0 2 4 35
ravigautam1896 1 1/1/0 1 1 34
Francisco Gamino 1 0/0/0 1 3 28
Chris Rosenblatt (crosenblatt) 1 1/0/0 2 1 26
Ramneet Tung (ramneettung-msft) 1 1/0/0 1 1 26
Xiaofei Cao 1 2/2/0 2 2 24
Dhruvil Shah 1 0/0/0 1 3 24
Peng Jiahui 2 2/0/0 2 2 23
Dapeng Zhang 1 3/1/2 2 2 23
Calvin S. 1 0/0/0 1 1 22
None (xuhumsft) 1 4/4/0 3 1 20
wangbwn 1 0/0/0 1 2 19
tsaiggo 1 0/0/0 1 3 18
gaoyp830 1 1/1/0 1 1 14
miaxzhitong 1 1/1/0 1 3 14
Tim Lovell-Smith (TimLovellSmith) 1 1/0/0 1 1 12
None (NoaGoren-Microsoft) 1 1/1/0 1 1 9
hrjami 1 0/0/0 1 2 8
Shawn Fang 1 0/0/0 1 3 8
Nikhil Gupta 1 0/0/0 1 2 8
Richard Park (richardpark-msft) 1 1/0/0 2 1 8
Mark Cowlishaw 1 1/1/0 1 1 7
Haoling Dong 1 1/1/0 1 1 7
Wenjun Gao 1 1/1/0 1 3 6
ZhidaLiu 1 0/0/0 1 1 5
yuc-Li 1 0/0/0 1 1 4
nehalR12 1 0/0/0 1 1 4
Sameeksha Vaity 1 1/1/0 1 1 3
None (Rotem2dvir) 1 1/1/0 1 1 3
Richard Park 1 0/0/0 2 1 3
Weidong Xu 1 1/1/0 1 1 3
Dvir Naim 1 0/0/0 1 1 2
Yalin Li 1 2/1/0 1 1 2
Alan Zimmer 1 0/0/0 1 1 1
None (qfai) 0 1/0/0 0 0 0
None (ajtms) 0 1/0/0 0 0 0
Tianen (JackTn) 0 2/0/0 0 0 0
None (bjqian) 0 1/0/0 0 0 0
ILAVELAN KANNIAPPAN (ikanni) 0 1/0/0 0 0 0
None (nasc17) 0 1/0/0 0 0 0
Huimin Yan (hmyan90) 0 1/1/0 0 0 0
Paul Van Eck (pvaneck) 0 1/0/0 0 0 0
None (ryanosh) 0 1/0/1 0 0 0
None (talco77) 0 1/0/0 0 0 0
Chenyang Liu (zackliu) 0 1/0/0 0 0 0
Zunli Hu (Juliehzl) 0 2/1/0 0 0 0
Srinivas (alluri02) 0 1/0/0 0 0 0
None (avjerafi) 0 1/0/0 0 0 0
Cameron Taggart (cataggar) 0 1/0/0 0 0 0
None (dtuCloud) 0 2/1/1 0 0 0
Dudi Likvornik (dulikvor) 0 1/0/0 0 0 0
gigi (gigigoo0) 0 1/0/0 0 0 0
None (gubalasu) 0 1/0/0 0 0 0
None (hdmimsft) 0 1/0/0 0 0 0
Jitin John (jijohn14) 0 1/0/0 0 0 0
Micah McKittrick (mimckitt) 0 1/0/1 0 0 0
Naveed Aziz (naveedaz) 0 1/0/0 0 0 0
None (ragovada) 0 4/0/1 0 0 0
None (rwishahy) 0 1/0/0 0 0 0
Sandeep Prakash (saprakas) 0 1/0/0 0 0 0
None (surashed) 0 1/0/0 0 0 0
Jiao Di (MSFT) (v-jiaodi) 0 1/0/0 0 0 0
None (yitaopan) 0 5/1/2 0 0 0
None (amber-ccc) 0 1/0/0 0 0 0
None (bowenqin1) 0 1/1/0 0 0 0
Xu Xue (xuexu6666) 0 1/1/0 0 0 0
None (abdulgagit) 0 2/0/0 0 0 0
Max Podriezov (mpodriezov) 0 2/0/1 0 0 0
None (sidsinghms) 0 1/0/0 0 0 0
None (singhabh27) 0 2/0/0 0 0 0
None (gmgodwin-23) 0 1/0/0 0 0 0
Harry Li (harryli0108) 0 1/0/0 0 0 0
None (nikhilhope3) 0 1/0/0 0 0 0
None (rzhelenchuk) 0 1/0/0 0 0 0
None (bgashirabake) 0 1/1/0 0 0 0
Prajjwal Kamboj (kamboj-prjwl) 0 4/2/1 0 0 0
Arjun Patel (arjun-d-patel) 0 4/0/2 0 0 0
Ayush Gupta - SQL (guptaayush007) 0 1/0/1 0 0 0
Shalmoli Neogi (shalmolineogi) 0 2/0/1 0 0 0
None (skuchipudi295) 0 3/1/1 0 0 0
None (amruthashree18) 0 1/0/0 0 0 0
Joseph Lin (joslinmicrosoft) 0 1/0/0 0 0 0
Ivan Arandjelovic (ivanarandjelovic) 0 2/1/1 0 0 0
None (schaudhari6254888) 0 2/0/0 0 0 0
Vikas Choudhary (vikaschoudharycs097) 0 3/0/2 0 0 0

PRs: created by that dev and opened/merged/closed-unmerged during the period

Detailed Reports

Report On: Fetch issues



Recent Activity Analysis

The Azure REST API Specifications repository currently has 1,638 open issues, reflecting ongoing development and user engagement. Recent activity has seen a mix of bug reports, feature requests, and API reviews, indicating active participation from both the community and Microsoft teams. Notably, issues related to discrepancies between API specifications and actual service behavior are prevalent, suggesting a need for improved alignment between documentation and implementation.

Several issues exhibit common themes, such as inconsistencies in property naming conventions (e.g., casing changes), missing parameters in API responses, and confusion around expected behaviors of certain features. The presence of multiple bug reports related to identity properties and resource configurations also highlights potential gaps in the API's usability and clarity.

Issue Details

Most Recently Created Issues

  1. Issue #30419: [BUG] Azure AI Search datasource / indexer cannot run when "Cosmos DB Built-in Data Reader" assigned at database scope

    • Priority: Bug
    • Status: Open
    • Created: 1 day ago
    • Updated: N/A

  2. Issue #30411: [Swagger ApiDocPreview] Failing with "Get-AzAccessToken is not recognized"

    • Priority: Bug
    • Status: Open
    • Created: 1 day ago
    • Updated: N/A

  3. Issue #30409: [BUG] dns resolver pagination Swagger docs

    • Priority: Bug
    • Status: Open
    • Created: 2 days ago
    • Updated: 1 day ago

  4. Issue #30403: [BUG] calculateModelCapacity method returns 404

    • Priority: Bug
    • Status: Open
    • Created: 2 days ago
    • Updated: N/A

  5. Issue #30393: [Azure Container Apps - Azure Container Apps] API Review

    • Priority: API Review Scoping
    • Status: Open
    • Created: 4 days ago
    • Updated: N/A

Most Recently Updated Issues

  1. Issue #30411

    • Last updated by Nick Walker with confirmation that the issue has been fixed.

  2. Issue #30409

    • Updated with additional comments regarding the pagination issue.

  3. Issue #30390: [Question] How to know which OpenAI version to install for each Azure OpenAI API version?

    • Last updated with further inquiries about compatibility between Azure OpenAI API versions and their corresponding OpenAI library versions.

  4. Issue #30370: [FEATURE REQ] Implementation of TypeSpec 'infoblurb' Mechanism in Brownfield PRs

    • Updated with additional context on feature requirements.

  5. Issue #30295: [FEATURE REQ] AzureOpenAI support json_schema in response_format

    • Updated with requests for support on new features.

Summary of Themes and Commonalities

  • A significant number of issues focus on bugs related to API behavior that does not align with the documented specifications.
  • Many reports highlight problems with identity properties, particularly regarding casing inconsistencies.
  • Users are requesting clearer documentation and examples for newly introduced features, especially concerning compatibility between different versions of APIs.
  • There is a recurring need for better error handling and messaging within the APIs to guide users more effectively when encountering issues.

This analysis indicates that while there is robust community engagement, there are also substantial areas for improvement in terms of documentation accuracy and API reliability.

Report On: Fetch pull requests



Overview

The dataset includes a total of 683 open pull requests (PRs) from the Azure REST API Specifications repository, with a focus on various updates and enhancements to the API specifications. The PRs cover a wide range of topics, including new API versions, bug fixes, and improvements in documentation and examples.

Summary of Pull Requests

  1. PR #30435: Adding CreateCallFailed event to 2024-06-15-preview api-version. This PR introduces a new event to enhance the call automation capabilities.

  2. PR #30434: Add global suppressions for Lint diff failures. This draft PR aims to address linting issues by adding suppressions, ensuring smoother integration.

  3. PR #30433: Review request for Microsoft.DBforPostgreSQL to add version stable/2024-08-01. This PR introduces a stable version with significant new features such as geo-replication and enhanced backup options.

  4. PR #30432: Updating Vnet-related APIs to Swagger. This PR focuses on updating existing APIs related to virtual networks, ensuring they meet current standards.

  5. PR #30431: Add Microsoft.Web/staticSiteRegions API. A new API addition that enhances the capabilities of static site management within Azure.

  6. PR #30430: Add AOAI 2024-08-01 preview API release. This PR introduces a new preview API version for Azure OpenAI services.

  7. PR #30429: [draft] ignore. A placeholder PR that appears to be used for testing purposes without substantive changes.

  8. PR #30428: Prettier Gate fixes for Oct GA. This PR addresses formatting issues identified during the GA process.

  9. PR #30427: Testbranch1. A draft PR likely used for testing purposes without specific changes.

  10. PR #30426: [Relay] 2024-01-01. This PR introduces a new version for the Relay service, enhancing its functionality.

  11. PR #30425: Liftr-NewRelic Resubscribe API - 2024-10-01 stable version. This PR adds support for resubscribing to New Relic services.

  12. PR #30424: App data plane session breaking change. This PR addresses breaking changes in the app data plane specifications.

  13. PR #30423: Update Readme.md in standby pool. A minor update to the README file for clarity.

  14. PR #30422: update tspconfig.yaml for python. This PR updates configuration files to align with recent changes in TypeSpec usage.

  15. PR #30421: Add enableFips property for dedicated workload profiles. This PR introduces a new property that enhances security compliance options.

  16. PR #30420: document translation client.tsp updates for python. Updates related to the Document Translation service's client specifications.

  17. PR #30419: Release web 2024 04 01 - A significant update that includes multiple enhancements across various web services.

  18. PR #30418: Add support for more media message types - Enhancements to media message handling in Azure services.

  19. PR #30417: [Draft] Easy button related changes - Ongoing work on simplifying user interactions with Azure services.

  20. PR #30397: Swagger Release 2024-03-01 Lint Diff Violation Suppress - Addressing lint violations from previous releases.

Analysis of Pull Requests

The current set of pull requests reflects a robust activity within the Azure REST API Specifications repository, indicating ongoing development and enhancement efforts across various Azure services:

Themes and Commonalities

  1. New Features and Versions:

    • Many pull requests focus on introducing new API versions (e.g., #30433, #30430, and #30309). These updates often include significant enhancements such as improved functionalities or additional features that cater to evolving customer needs.
    • The introduction of new events and properties (e.g., CreateCallFailed in PR #30435 and enableFips in PR #30421) demonstrates an emphasis on enhancing existing capabilities while addressing security and compliance requirements.

  2. Documentation Improvements:

    • Several pull requests aim at improving documentation clarity and accuracy (e.g., updating README files or fixing example specifications). For instance, PRs like #30311 and #30322 focus on refining documentation to ensure it aligns with current standards and practices.
    • The inclusion of detailed explanations about changes in APIs (as seen in PRs like #30319) indicates a commitment to transparency and user guidance throughout the development process.

  3. Linting and Formatting Fixes:

    • There is a noticeable trend towards addressing linting issues (e.g., PRs like #30428 and #30397). These efforts are crucial in maintaining code quality and ensuring adherence to coding standards across the repository.
    • The focus on suppressing lint errors through global settings (as seen in PRs like #30434) suggests an ongoing effort to streamline development processes while minimizing disruptions caused by formatting discrepancies.

Anomalies

  1. Stale Pull Requests:

    • Some pull requests appear to be drafts or placeholders (e.g., PRs like #30429 and #30296), which may indicate areas where contributors are still formulating their approaches or awaiting further input before proceeding.
    • The presence of multiple draft pull requests may also suggest potential bottlenecks in review processes or resource allocation within teams responsible for these contributions.

  2. High Volume of Open Issues:

    • With over 2,321 open issues alongside the active pull requests, there is an indication of substantial ongoing work within the repository, which might lead to delays in merging or reviewing contributions if not managed effectively.
    • The high number of open issues could also reflect challenges faced by contributors when navigating the complexities of Azure's extensive API landscape or responding to evolving customer requirements.

Lack of Recent Merge Activity

  • The analysis reveals that while there is significant activity in terms of creating new pull requests, there may be a lack of recent merge activity across some areas, particularly older pull requests that have not yet been addressed.
  • This could potentially hinder progress if critical updates remain unmerged, impacting overall project timelines and responsiveness to user feedback or market demands.

In conclusion, while the Azure REST API Specifications repository showcases strong community engagement and active development efforts through numerous pull requests, attention must be given to managing review processes effectively, addressing stale contributions, and ensuring timely merges to maintain momentum within this critical project area.

Report On: Fetch commits



Repo Commits Analysis

Development Team and Recent Activity

Team Members and Their Recent Activities

  1. Yuchao Yan

    • Collaborated on multiple commits, including updating tspconfig.yaml for Python and fixing issues in various specifications.
    • Worked on adding new API versions and updating existing ones, such as for Microsoft.Databricks and Microsoft.Cache.
    • Co-authored several changes related to suppressions and linting issues.

  2. Abhay Pratap

    • Focused on resolving issues related to subscription operations, including adding new API versions and fixing lint errors.
    • Co-authored changes that involved significant updates to the Microsoft.Subscription API.

  3. Mike Harder

    • Engaged in dependency upgrades and automated updates via Dependabot.
    • Contributed to the maintenance of the repository by addressing various issues and merging branches.

  4. Priyankarking

    • Worked on updating the Redis Enterprise API specifications, including adding new examples and modifying existing ones for the 2024-09-01 version.

  5. Jaskirat Singh

    • Made changes to the SAP Virtual Instance management specifications, focusing on new GA API updates for 2024-09-01.

  6. Alfredo Santamaria

    • Contributed to updating Service Fabric Managed Clusters with new examples and API versioning.

  7. Badea Marjieh

    • Involved in fixing TypeSpec issues and making updates to Fabric management specifications.

  8. Ramneet Tung

    • Added a new event type (CreateCallFailed) to the Call Automation API for the 2024-06-15-preview version.

  9. Samir Solanki

    • Merged branches and updated various configurations, including those related to Azure API Management.

  10. Chenxi Jiang

    • Updated Python configurations across multiple services and contributed to fixing formatting issues in specifications.

Patterns, Themes, and Conclusions

  • Active Collaboration: Multiple team members are frequently co-authoring commits, indicating a collaborative environment where knowledge sharing is encouraged.

  • Focus on API Versioning: A significant number of recent commits involve adding or updating API versions across various Azure services, reflecting ongoing development efforts to keep APIs current with evolving requirements.

  • Maintenance and Bug Fixes: There is a consistent effort in maintaining the quality of the repository through bug fixes, dependency upgrades, and addressing linting issues.

  • Community Engagement: The repository's activity level suggests strong community involvement, with many contributors actively participating in discussions around improvements and feature additions.

Overall, the development team is actively engaged in enhancing Azure's REST API specifications through collaborative efforts, focusing on version updates, maintenance tasks, and community contributions.