@phdthesis {2025:phd:souhaila-serbout,
	title = {Web API Design and Evolution},
	year = {2025},
	month = {February},
	school = {USI},
	type = {PhD},
	address = {Lugano},
	abstract = {Web APIs (Application Programming Interfaces) are a cornerstone of modern software development, enabling interoperability and integration across diverse systems. Despite their importance, there is a lack of large-scale empirical studies on the design, evolution, and versioning of APIs. This research addresses this gap by leveraging a comprehensive dataset of OpenAPI Specifications (OAS) from public repositories such as GitHub and SwaggerHub. The thesis provides empirical results describing the Web API landscape, focusing on structural patterns, design smells, changes, and versioning practices.

Through mining commit histories and metadata, the study identifies trends in API evolution and assesses their adherence to versioning principles. Clustering techniques and natural language processing are employed to detect common structural patterns and understand the semantic context of API elements. The research adopts a language-agnostic, automated approach to analyze API design and evolution at scale. The goal is to answer questions on Web API design and evolution without being tied to a specific programming ecosystem. 

We empirically identified four recurring structural patterns in Web API designs to provide access to enumerable, dependable, and mutable collections, which serve as modular and reusable building blocks. Additionally, the analysis uncovers design smells that hinder usability, maintainability, and security, providing actionable insights to improve API quality.

Web API structures are inherently tied to the operations they provide for handling resources derived from specific data models. As such, studying APIs requires a dual focus on their structural design and the underlying data models to ensure coherence. We examined the relationship between API structures and their data models, highlighting frequent misalignments with design principles such as logical structuring and consistent naming conventions. 

Regarding API evolution, the study categorizes over 200 types of changes and reveals that breaking changes occur 2.44 times more often than non-breaking ones. While many breaking changes appear minor, their cumulative impact on client applications can be significant.

When it comes to Web API versioning, we detected a high level of diversity in the adopted versioning schemes. In addition, APIs that claimed to use Semantic Versioning often failed to adhere to its basic rules. 

The findings reveal that while Web APIs have been part of the software landscape since more than 20 years, they still do not meet the theoretical design principles when it comes to their practical implementation and management. This is explained by the lack of straightforward tools that can guide developers in adhering to best practices, identifying design flaws, and ensuring consistent versioning and evolution management throughout the API lifecycle.

In light of this empirical evidence, we propose supporting both API developers and users through language-agnostic visualization tools that can be integrated into development environments (IDE-based) or easily accessible for users who only want to learn about the API (web-based). The proposed tools are initial research prototypes built based on our findings. OAS2tree enhances API feature navigation and integrates functionality to identify and flag potential design flaws. APIcture offers a picture of API histories, providing an intuitive way to track their evolution. 
Although effective in their initial form, these tools have the potential to be further refined through user feedback and studies involving the target audience, ultimately improving their features, usability, and impact. },
	keywords = {API Analytics},
	author = {Souhaila Serbout}
}
