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.
This is a preview of subscription content, log in via an institution to check access.
Access this chapter
Tax calculation will be finalised at checkout
Purchases are for personal use only
Similar content being viewed by others
References
Semantic Versioning. https://semver.org/
OpenAPI Initiative. https://www.openapis.org/
https://github.com/USI-INF-Software/API-Versioning-practices-detection
SwaggerHub. https://app.swaggerhub.com/
Release naming conventions. https://www.drupal.org/node/1015226
https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/
SWR Audio Lab - Radiohub API. https://github.com/swrlab/swrlab/blob/main/openapi/openapi.yaml
Bogart, C., Kästner, C., Herbsleb, J., Thung, F.: How to break an API: cost negotiation and community values in three software ecosystems. In: Proceedings of the 24th International Symposium on Foundations of Software Engineering (FSE), pp. 109–120 (2016)
Decan, A., Mens, T., Mazrae, P.R., Golzadeh, M.: On the use of GitHub actions in software development repositories. In: International Conference on Software Maintenance and Evolution (ICSME), pp. 235–245 (2022)
Di Lauro, F., Serbout, S., Pautasso, C.: A large-scale empirical assessment of web API size evolution. J. Web Eng. 21(6), 1937–1980 (2022)
Dietrich, J., Pearce, D., Stringer, J., Tahir, A., Blincoe, K.: Dependency versioning in the wild. In: Proceedings of the 16th International Conference on Mining Software Repositories (MSR), pp. 349–359 (2019)
Lauret, A.: The Design of web APIs. Simon and Schuster (2019)
Lübke, D., Zimmermann, O., Pautasso, C., Zdun, U., Stocker, M.: Interface evolution patterns: balancing compatibility and extensibility across service life cycles. In: Proceedings of the 24th EuroPLoP (2019)
Marquardt, K.: Patterns for software release versioning. In: Proceedings of the 15th European Conference on Pattern Languages of Programs (EuroPLoP) (2010)
Ochoa, L., Degueule, T., Falleri, J.R., Vinju, J.: Breaking bad? Semantic versioning and impact of breaking changes in maven central. Empir. Softw. Eng. 27(3), 1–42 (2022)
Raatikainen, M., Kettunen, E., Salonen, A., Komssi, M., Mikkonen, T., Lehtonen, T.: State of the practice in application programming interfaces (APIs): a case study. In: Biffl, S., Navarro, E., Löwe, W., Sirjani, M., Mirandola, R., Weyns, D. (eds.) ECSA 2021. LNCS, vol. 12857, pp. 191–206. Springer, Cham (2021). https://doi.org/10.1007/978-3-030-86044-8_14
Serbout, S., Di Lauro, F., Pautasso, C.: Web APIs structures and data models analysis. In: Companion Proceedings of the 19th International Conference on Software Architecture (ICSA), pp. 84–91 (2022)
Varga, E.: Creating Maintainable APIs. APress (2016)
Yang, J., Wittern, E., Ying, A.T., Dolby, J., Tan, L.: Towards extracting web API specifications from documentation. In: Proceedings of the 15th International Conference on Mining Software Repositories (MSR), pp. 454–464 (2018)
Zhang, L., et al.: Has my release disobeyed semantic versioning? Static detection based on semantic differencing. In: Proceedings of the 37th International Conference on Automated Software Engineering (2023)
Zimmermann, O., Stocker, M., Lübke, D., Zdun, U., Pautasso, C.: Patterns for API Design - Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley (2022)
Acknowledgements
The authors acknowledge Fabio Di Lauro for gathering the raw dataset, and Deepansha Chowdhary for conducting a feasibility study on it. This work was supported by the SNF with the API-ACE project number 184692.
Author information
Authors and Affiliations
Corresponding author
Editor information
Editors and Affiliations
Rights and permissions
Copyright information
© 2023 The Author(s), under exclusive license to Springer Nature Switzerland AG
About this paper
Cite this paper
Serbout, S., Pautasso, C. (2023). An Empirical Study of Web API Versioning Practices. In: Garrigós, I., Murillo Rodríguez, J.M., Wimmer, M. (eds) Web Engineering. ICWE 2023. Lecture Notes in Computer Science, vol 13893. Springer, Cham. https://doi.org/10.1007/978-3-031-34444-2_22
Download citation
DOI: https://doi.org/10.1007/978-3-031-34444-2_22
Published:
Publisher Name: Springer, Cham
Print ISBN: 978-3-031-34443-5
Online ISBN: 978-3-031-34444-2
eBook Packages: Computer ScienceComputer Science (R0)