@conference {apiace:2024:msr, title = {APIstic: A Large Collection of OpenAPI Metrics}, booktitle = {21st IEEE/ACM International Conference on Mining Software Repositories (MSR)}, year = {2024}, note = {(to appear)}, month = {April}, address = {Lisbon, Portugal}, abstract = {In the rapidly evolving landscape of web services, the significance of efficiently designed and well-documented APIs is paramount. In this paper, we present APIstic an API analytics dataset and exploration tool to navigate and segment APIs based on an extensive set of precomputed metrics extracted from OpenAPI specifications, sourced from GitHub, SwaggerHub, BigQuery and APIs.guru. These pre-computed metrics are categorized into structure, data model, natural language description, and security metrics. The extensive dataset of varied API metrics provides crucial insights into API design and documentation for both researchers and practitioners. Researchers can use APIstic as an empirical resource to extract refined samples, analyze API design trends, best practices, smells, and patterns. For API designers, it serves as a benchmarking tool to assess, compare, and improve API structures, data models, and documentation using metrics to select points of references among 1,275,568 valid OpenAPI specifications. The paper discusses potential use cases of the collected data and presents a descriptive analysis of selected API analytics metrics. }, keywords = {dataset, metrics, OpenAPI}, author = {Souhaila Serbout and Cesare Pautasso} } @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}, address = {Tampere, Finland}, keywords = {API Analytics, API Evolution, Semantic Versioning, Web API}, author = {Souhaila Serbout and Cesare Pautasso} } @conference {apiace:2023:europlop, title = {API Rate Limit Adoption - A Pattern Collection}, booktitle = {28th European Conference on Pattern Languages of Programs (EuroPLoP 2023)}, year = {2023}, month = {July}, publisher = {ACM}, organization = {ACM}, address = {Kloster Irsee, Germany}, keywords = {API Design Patterns}, doi = {10.1145/3628034.3628039}, url = {https://dl.acm.org/doi/10.1145/3628034.3628039}, author = {Souhaila Serbout and Amine El Malki and Cesare Pautasso and Uwe Zdun} } @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:2023:vissoft, title = {Interactively exploring API changes and versioning consistency}, booktitle = {11th IEEE Working Conference on Software Visualization (VISSOFT 2023)}, year = {2023}, month = {October}, pages = {28-39}, publisher = {IEEE}, organization = {IEEE}, address = {Bogota, Colombia}, abstract = {Application Programming Interfaces (APIs) evolve over time. As they change, they are expected to be versioned based on how changes might affect their clients. In this paper, we present two novel visualizations specifically designed to represent all structural changes and the level of adherence to semantic versioning practices over time. They can also serve for characterizing and comparing the evolution history of different Web APIs. The API VERSION CLOCK helps to visualize the sequence of API changes over time and highlight inconsistencies between major, minor, or patch version changes and the corresponding introduced breaking or non-breaking changes applied to the API. The API CHANGES overview aggregates all changes to an OpenAPI (OAS) description, highlighting the unstable vs. the stable elements of the API over its entire history. Both visualizations can be automatically created using the APICTURE, a command-line and web-based tool that analyzes the histories of git code repositories containing OAS descriptions, extracting the necessary data for generating visualizations and computing metrics related to API evolution and versioning. The visualizations have been successfully applied to classify, compare, and interactively explore the multi-year evolution history of APIs with up to hundreds of individual commits.}, keywords = {API Versioning; Software Visualization}, doi = {10.1109/VISSOFT60811.2023.00013}, url = {https://ieeexplore.ieee.org/document/10350155}, author = {Souhaila Serbout and Diana Carolina Mu{\~n}oz Hurtado and Cesare Pautasso} } @demo {2022:ecsa:expresso, title = {ExpressO: From Express.js implementation code to OpenAPI interface descriptions}, year = {2022}, month = {September}, pages = {29{\textendash}44}, publisher = {Springer}, abstract = {This tool demo paper brings forward a new CLI tool called ExpressO for developers who need to analyze a Web API implemented using the Express.js framework and automatically extract a specification written in the standard OpenAPI interface description language. The specification includes all of the implemented endpoints along with their response status codes and path and query parameters. Developers can use it to automatically determine whether the interface of a Web API matches its implementation based on the Express.js framework. The tool has been released on the npm component registry as {\textquoteleft}expresso-api{\textquoteright}. }, keywords = {API, express.js, OpenAPI}, doi = {10.1007/978-3-031-36889-9_4}, author = {Souhaila Serbout and Alessandro Romanelli 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}, 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}, author = {Souhaila Serbout and Cesare Pautasso and Uwe Zdun} } @article {2022:jwe, title = {A Large-scale Empirical Assessment of Web API Size Evolution}, journal = {Journal of Web Engineering}, volume = {21}, year = {2022}, month = {November}, pages = {1937{\textendash}1980}, abstract = {Like any other type of software, also Web Application Programming Interfaces (APIs) evolve over time. In the case of widely used API, introducing changes is never a trivial task, because of the risk of breaking thousands of clients relying on the API. In this paper we conduct an empirical study over a large collection of OpenAPI descriptions obtained by mining open source repositories. We measure the speed at which Web APIs change and how changes affect their size, simply defined as the number of operations. The dataset of API descriptions was collected over a period of one year and includes APIs with histories spanning across up to 7 years of commits. The main finding is that APIs tend to grow, although some do reduce their size, as shown in the case study examples included in the appendix.}, keywords = {API Evolution}, doi = {10.13052/jwe1540-9589.2167}, url = {https://ieeexplore.ieee.org/document/10246943}, author = {Fabio Di Lauro and Souhaila Serbout and Cesare Pautasso} } @article {2022:sosym:bpmn, title = {Live process modeling with the BPMN Sketch Miner}, journal = {Software and Systems Modeling}, volume = {21}, year = {2022}, month = {October}, pages = {1877{\textendash}1906}, abstract = {BPMN Sketch Miner is a modeling environment for generating visual business process models starting from constrained natural language textual input. Its purpose is to support business process modelers who need to rapidly sketch visual BPMN models during interviews and design workshops, where participants should not only provide input but also give feedback on whether the sketched visual model represents accurately what has been described during the discussion. In this article, we present a detailed description of the BPMN Sketch Miner design decisions and list the different control flow patterns supported by the current version of its textual DSL. We also summarize the user study and survey results originally published in MODELS 2020 concerning the tool usability and learnability and present a new performance evaluation regarding the visual model generation pipeline under actual usage conditions. The goal is to determine whether it can support a rapid model editing cycle, with live synchronization between the textual description and the visual model. This study is based on a benchmark including a large number of models (1350 models) exported by users of the tool during the year 2020. The main results indicate that the performance is sufficient for a smooth live modeling user experience and that the end-to-end execution time of the text-to-model-to-visual pipeline grows linearly with the model size, up to the largest models (with 195 lines of textual description) found in the benchmark workload.}, keywords = {BPMN, text to visual, Textual Modelling DSL}, issn = {1619-1366}, doi = {10.1007/s10270-022-01009-w}, url = {https://link.springer.com/article/10.1007/s10270-022-01009-w$\#$citeas}, author = {Ana Ivanchikj and Souhaila Serbout and Cesare Pautasso} } @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} } @conference {2021:europlop:api-fragments, title = {From OpenAPI Fragments to API Pattern Primitives and Design Smells}, booktitle = {European Conference on Pattern Languages of Programs (EuroPLoP{\textquoteright}21)}, year = {2021}, month = {July}, publisher = {ACM}, organization = {ACM}, address = {Virtual Kloster Irsee, Germany}, abstract = {In the past few years, the OpenAPI Specification (OAS) has emerged as a standard description language for accurately modeling Web APIs. Today, thousands of OpenAPI descriptions can be found by mining open source repositories. In this paper, we attempt to exploit these artifacts to extract commonly occurring building blocks used in Web API structures, in order to assist Web API designers in their modelling task. Our work is based on a fragmentation mechanism, that starts from OpenAPI descriptions of Web APIs to extract their structures, then fragment these structures into smaller blocks. This approach enabled us to extract a large dataset of reoccurring fragments from a collection of 6619 API specifications. Such fragments have been found multiple times in the same or across different APIs. We have classified the most reoccurring fragments into four pattern primitives used to expose in the API access to collections of items. We distinguish for each primitive variants from design smells. This classification is based on the specific combinations of operations associated with the collection items and on an in-depth analysis of their natural language labels and descriptions. The resulting pattern primitives are intended to support designers who would like to introduce one or more collections for a specific class of items in their HTTP-based API.}, keywords = {API, API fragments, design smells, OpenAPI, patterns}, doi = {10.1145/3489449.3489998}, url = {https://zenodo.org/record/5727094$\#$.YZ97mFMo-0o}, author = {Souhaila Serbout and Cesare Pautasso and Uwe Zdun and Olaf Zimmermann} } @conference {2021:icwe:api-evolution, title = {Towards Large-scale Empirical Assessment of Web APIs Evolution}, booktitle = {21st International Conference on Web Engineering (ICWE2021)}, year = {2021}, month = {May}, pages = {124-138}, publisher = {Springer}, organization = {Springer}, address = {Biarritz, France}, abstract = {Web Application Programming Interfaces (APIs) decouple the internal implementation of a service from its consumers which can reuse and compose them to rapidly build new applications. Many Web APIs are described with the OpenAPI Specification (OAS). The goal of our research is to check the feasibility of using API descriptions found in public open source repositories to study how APIs evolve over time. To do so, we collected a large dataset of OAS documents by crawling open source repositories, we parsed the corresponding metadata and measured the API size in order to extract a simple model to track the lifecycle of API artifacts and observe common evolution behaviors. Our preliminary results indicate that only a subset of the APIs changes, but as opposed to the expectation that APIs should only grow to maintain backward compatibility we also detected a number of APIs with a more variable history. We also study the stability of API artifacts over time and whether APIs are more or less likely to change as they age.}, keywords = {API Evolution, OpenAPI, Web API}, doi = {10.1007/978-3-030-74296-6_10}, author = {Fabio Di Lauro and Souhaila Serbout and Cesare Pautasso} } @conference {2020:bpmn-sketch-miner:models, title = {From Text to Visual BPMN Process Models: Design and Evaluation}, booktitle = {23rd International Conference on Model Driven Engineering Languages and Systems (MODELS)}, year = {2020}, month = {October}, pages = {229{\textendash}239}, publisher = {ACM/IEEE}, organization = {ACM/IEEE}, address = {Montreal, Canada}, abstract = {Most existing Business Process Model and Notation (BPMN) editing tools are graphical, and as such based on explicit modeling, requiring good knowledge of the notation and its semantics, as well as the ability to analyze and abstract business requirements and capture them by correctly using the notation. As a consequence, their use can be cumbersome for live modeling during interviews and design workshops, where participants should not only provide input but also give feedback on how it has been represented in a model. To overcome this, in this paper we present the design and evaluation of BPMN Sketch Miner, a tool which combines notes taking in constrained natural language with process mining to automatically produce BPMN diagrams in real time as interview participants describe them with stories. In this work we discuss the design decisions regarding the trade-off between using mining vs. modelling in order to: 1) support a larger number of BPMN constructs in the textual language; 2) target both BPMN beginners and business analysts, in addition to the process participants themselves. The evaluation of the new version of the tool in terms of how it balances the expressiveness and learnability of its DSL with the usability of the text-to-visual sketching environment shows encouraging results. Namely while BPMN beginners could model a non-trivial process with the tool in a relatively short time and with good accuracy, business analysts appreciated the usability of the tool and the expressiveness of the language in terms of supported BPMN constructs.}, keywords = {BPMN, domain specific languages, live modeling, text to visual}, doi = {10.1145/3365438.3410990}, author = {Ana Ivanchikj and Souhaila Serbout and Cesare Pautasso} }