API Design Guidelines Impact

By Christos Gkoros

May 25, 2024

A list of key finding to illustrate the impact of AIP Guidelines in the areas of API consumption and API production:

API Production:

Increased Requirement Fulfillment: A controlled developer experiment showed that developers using API Improvement Proposals (AIPs) and an API linter achieved a 10% higher requirement fulfillment rate compared to those without any protocols.
Feedback Utility: Among developers using the linter tool alongside AIPs, 75% found it beneficial, aiding significantly in refining their API designs.
Learning Curve: A noticeable learning curve was present, especially for first-time AIP users, who reported challenges integrating documentation and coding practices.
Positive Perception of AIPs: A high majority (91%) of developers who used AIPs agreed that these protocols were helpful in the API design process.

API Consumption:

Preference for AIP-aligned Designs: A significant portion of API consumers (73% of survey participants) expressed a preference for API designs that aligned with AIPs, praising the enhanced usability and comprehensibility these designs offered.
Diverse Experience Levels: The study engaged API consumers with a range of industry experiences, where 56% had less than 7 years and 44% had more than 7 years, demonstrating broad applicability of the findings across experience levels.
Quantitative Assessments by AI: The AI-based tool, API Architect, scored API designs, with those using both AIPs and the API linter generally receiving higher scores. This aligns with the preferences of 73% of human experts who favored these designs.

API Consumers with Less Than 7 Years of Experience:

Emphasis on Readability and Usability: Consumers with less than 7 years of experience prioritized technical proficiency and dexterity, favoring APIs that were readable and easy to understand.
Preference for Comprehensible APIs: This group valued APIs that allowed them to clearly comprehend the functionality and structure upon reviewing the code, emphasizing the importance of readability in their API assessments.

API Consumers with More Than 7 Years of Experience:

Focus on Business Goals and Adaptability: Consumers with more than 7 years of experience prioritized broader business goals and adaptability, valuing APIs that were agile and suitable for end-user needs.
Assessment of Business Value and Problem Solving: They scrutinized APIs based on their ability to deliver business value and solve problems effectively, reflecting a product-oriented and strategic perspective in their evaluations.