@conference {apiace:2025:icsa,
	title = {Mining Security Documentation Practices in OpenAPI Descriptions},
	booktitle = {22nd IEEE International Conference on Software Architecture (ICSA)},
	year = {2025},
	month = {March},
	address = {Odense, Denmark},
	abstract = {Security is an integral requirement of any trustworthy software architecture, particularly critical for application programming interfaces (APIs). In this paper, we survey security documentation practices, specifically API security schemes related to authentication and authorization, by mining a large collection of OpenAPI descriptions retrieved from open-source GitHub repositories. Our study focuses on detecting existing security schemes and evaluating their prevalence and positioning within API descriptions. We distinguish whether security schemes are introduced locally (at the path or operation level) or globally (for the entire API). Our analysis highlights scenarios where security schemes are featured in APIs in different proportions over time, thus tracking whether the API documentation tends to include more (or less) security details as the API evolves.},
	keywords = {API Analytics, OpenAPI, Security},
	author = {Diana Carolina Mu{\~n}oz Hurtado and Souhaila Serbout and Cesare Pautasso}
}
@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}
}
@conference {apiace:2024:icwe,
	title = {How Many Web APIs Evolve Following Semantic Versioning?},
	booktitle = {24th International Conference on Web Engineering (ICWE)},
	year = {2024},
	month = {June},
	publisher = {Springer},
	organization = {Springer},
	address = {Tampere, Finland},
	abstract = {More and more Web APIs use semantic versioning to represent the impact of changes on clients depending on previous versions. Our goal is to provide insights about the extent to which evolving Web APIs align with semantic versioning rules. In this paper we present the results of an empirical study on the descriptions of 3 075 Web APIs, which released at least one new version throughout their history. The APIs descriptions were mined by retrieving 132 909 commits from 2 028 different open source GitHub repositories. We systematically collected and examined 506 273 changes of 195 different types released within 16 053 new API versions. We classified whether each change is likely to break clients or not, and checked whether the corresponding version identifier has been updated following semantic versioning rules. The results indicate that in the best case, only 517 APIs consistently release major upgrades when introducing breaking changes, while 1 970 APIs will not always correctly inform their clients about breaking changes released as part of minor or patch-level upgrades. We also detected 927 APIs which use a backwards-compatible evolution strategy, as they never introduce any breaking change throughout their history.},
	keywords = {API Analytics, API Evolution, Semantic Versioning, Web API},
	doi = {10.1007/978-3-031-62362-2_25},
	url = {https://link.springer.com/chapter/10.1007/978-3-031-62362-2_25},
	author = {Souhaila Serbout and Cesare Pautasso}
}
@demo {apiace:2024:ecsa,
	title = {OAS2Tree: Visual API-First Design},
	year = {2024},
	month = {September},
	publisher = {Springer},
	address = {Luxembourg},
	abstract = {OAS2Tree is a tool designed to transform OpenAPI Specification (OAS) documents into tree-like visualizations, aiding in the understanding and navigation of the structure of REST APIs. By converting the detailed, verbose, and often complex OAS files into a visual tree structure, OAS2tree simplifies the comprehension of a Web API, highlighting the hierarchical relationships between endpoints, operations, and parameters. This visual representation is particularly useful for developers and stakeholders who need a quick overview of an API without delving into the intricate details of its technical specifications. OAS2tree can be integrated into the IDE through a Visual Studio code extension or used as a standalone web application. The tool currently has about 400 users and has been used on teaching, research, and development projects. In this paper, we present the design and implementation of OAS2tree, highlighting its features and use cases. We also highlight the limitations of the current version and discuss future improvements and potential extensions.},
	keywords = {API Analytics, demo, visualization},
	author = {Souhaila Serbout and Cesare Pautasso}
}
@conference {apiace:2023:icwe,
	title = {An empirical study of Web API versioning practices},
	booktitle = {23rd International Conference on Web Engineering (ICWE)},
	year = {2023},
	month = {June},
	publisher = {Springer},
	organization = {Springer},
	address = {Alicante, Spain},
	abstract = {As Web APIs evolve, developers assign them version identifiers to reflect the amount and the nature of changes that the API clients should expect. In this work we focus on identifying versioning practices adopted by Web API developers by extracting and classifying version identifiers found in a large collection of OpenAPI descriptions.
In particular, we observe how frequently different versioning schemes have been adopted for identifying both stable and preview releases (e.g., simple version counters, semantic versioning, or release timestamps). We further study the stability of versioning schemes during APIs evolution. We also detect APIs which offer dynamic access to versioning metadata through dedicated endpoints as well as APIs which support clients expecting to reach up to 14 different versions of the same API at the same time.
Overall the results offer a detailed view over current Web API versioning practices and can serve as the basis for future discussions on how to standardize critical API versioning metadata.},
	keywords = {API Analytics, Versioning},
	author = {Souhaila Serbout and Cesare Pautasso}
}
@conference {apiace:2022:icws,
	title = {How Composable is the Web? An Empirical Study on OpenAPI Data model Compatibility},
	booktitle = {IEEE World Congress on Services (ICWS Symposium on Services for Machine Learning)},
	year = {2022},
	month = {July},
	pages = {415-424},
	publisher = {IEEE},
	organization = {IEEE},
	address = {Barcelona, Spain},
	abstract = {Composing Web APIs is a widely adopted practice by developers to speed up the development process of complex Web applications, mashups, and data processing pipelines. However, since most publicly available APIs are built independently of each other, developers often need to invest their efforts in solving incompatibility issues by writing ad-hoc glue code, adapters and message translation mappings. How likely are Web APIs to be directly composable?

The paper presents an empirical study to determine the potential composability of a large collection of 20,587 public Web APIs by verifying their schemas{\textquoteright} compatibility. We define three levels of data model elements compatibility -- considering matches between property names and/or data types -- which can be determined statically based on API descriptions conforming to the OpenAPI specification. The study research questions address: to which extent are Web APIs compatible; the average number of compatible endpoints within each API; the likelihood of finding two APIs with at least one pair of compatible endpoints. 

To perform the analysis we developed a compatibility checker tool which can statically determine API schema compatibility on the three levels and find matching pairs of API responses which can be directly forwarded as requests to the same or other APIs. We run the tool on a dataset of 751,390 request and response message schemas extracted from publicly available OpenAPI descriptions.

The results indicate a relatively high number of compatible APIs when matching their data models only on the level of their elements{\textquoteright} data type. However, this number gets lower narrowing the scope to only the ones handling data objects having identical properties name. The average likelihood of finding two compatible APIs with both matching property names and data types reaches 21\%. Also, the number of compatible endpoints within the same API is very low.},
	keywords = {API Analytics, empirical study, mashups, OpenAPI, Web APIs},
	doi = {10.1109/ICWS55610.2022.00068},
	author = {Souhaila Serbout and Cesare Pautasso and Uwe Zdun}
}
@conference {apiace:2022:ecsa,
	title = {To deprecate or to simply drop operations? An empirical study on the evolution of a large OpenAPI collection},
	booktitle = {16th European Conference on Software Architecture (ECSA)},
	volume = {13444},
	year = {2022},
	month = {September},
	pages = {38-46},
	publisher = {Springer},
	organization = {Springer},
	address = {Prague, Czech Republic},
	keywords = {API Analytics, API Evolution},
	doi = {doi.org/10.1007/978-3-031-16697-6_3},
	author = {Fabio Di Lauro and Souhaila Serbout and Cesare Pautasso}
}
@conference {2022:icsa,
	title = {Web APIs Structures and Data Models Analysis},
	booktitle = {19th IEEE International Conference on Software Architecture (ICSA 2022)},
	year = {2022},
	month = {March},
	publisher = {IEEE},
	organization = {IEEE},
	address = {Honululu, Hawaii},
	abstract = {Microservice architectures emphasize keeping components small, to foster autonomy, low coupling, and independent evolution. In this large-scale empirical study, we measure the size of Web API specifications mined from open source repositories. These APIs are modeled using the OpenAPI Specification (OAS), which, in addition to documenting the offered operations, also contain schemas definitions for the data exchanged with the API request and response message payloads.  This study has as a goal to build empirical knowledge about:  (1) How big and diverse are real-world web APIs both in terms of their operations and data, (2) How different API structures use and reuse schema definitions. By mining public software repositories on Github, we gathered 42,194 valid OAS specifications published between 2014-2021. },
	keywords = {API Analytics, API Size, OpenAPI},
	author = {Souhaila Serbout and Fabio Di Lauro and Cesare Pautasso}
}
