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.
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/
Bogart, C., Kästner, C., Herbsleb, J., Thung, F.: When and how to make breaking changes: policies and practices in 18 open source software ecosystems. ACM TOSEM 30(4), 1–56 (2021)
Daigneau, R.: Service Design Patterns: Fundamental Design Solutions for SOAP/WSDL and Restful Web Services. Addison-Wesley, Boston (2012)
Dietrich, J., Pearce, D., Stringer, J., Tahir, A., Blincoe, K.: Dependency versioning in the wild. In: Proceedings of 16th International Conference on Mining Software Repositories (MSR), pp. 349–359 (2019)
Giretti, A.: API versioning. In: Beginning gRPC with ASP.NET Core 6, pp. 223–237 (2022)
Henning, M.: API design matters. Queue 5(4), 24–36 (2007)
Lam, P., Dietrich, J., Pearce, D.J.: Putting the semantics into semantic versioning. In: Proceedings of the 2020 ACM SIGPLAN International Symposium on New Ideas, New Paradigms, and Reflections on Programming and Software, pp. 157–179 (2020)
Lamothe, M., Guéhéneuc, Y.G., Shang, W.: A systematic review of API evolution literature. ACM Comput. Surv. (CSUR) 54(8), 1–36 (2021)
Li, W., Wu, F., Fu, C., Zhou, F.: A large-scale empirical study on semantic versioning in golang ecosystem. In: Proceedings of 38th IEEE/ACM International Conference on Automated Software Engineering (ASE), pp. 1604–1614. IEEE (2023)
Medjaoui, M., Wilde, E., Mitra, R., Amundsen, M.: Continuous API Management. O’Reilly, Sebastopol (2021)
OASDiff. https://github.com/Tufin/oasdiff
Ochoa, L., Degueule, T., Falleri, J.R.: Breakbot: analyzing the impact of breaking changes to assist library evolution. In: Proceedings of 44th International Conference on Software Engineering (ICSE): New Ideas and Emerging Results, pp. 26–30 (2022)
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)
OpenAPI Initiative. https://www.openapis.org/
Peralta, J.H.: Microservice APIs: Using Python, Flask, FastAPI, OpenAPI and More. Simon and Schuster, New York (2023)
Pinckney, D., Cassano, F., Guha, A., Bell, J.: A large scale analysis of semantic versioning in NPM. In: IEEE International Working Conference on Mining Software Repositories (2023)
Raemaekers, S., van Deursen, A., Visser, J.: Semantic versioning and impact of breaking changes in the maven repository. J. Syst. Softw. 129, 140–158 (2017)
Serbout, S., Muñoz Hurtado, D.C., Pautasso, C.: Interactively exploring API changes and versioning consistency. In: Proceedings of 11th IEEE Working Conference on Software Visualization (VISSOFT), pp. 28–39 (2023)
Serbout, S., Pautasso, C.: An empirical study of web API versioning practices. In: Garrigós, I., Murillo Rodríguez, J.M., Wimmer, M. (eds.) ICWE 2023. LNCS, vol. 13893, pp. 303–318. Springer, Cham (2023). https://doi.org/10.1007/978-3-031-34444-2_22
Serbout, S., Pautasso, C.: APIstic: a large collection of OpenAPI metrics. In: Proceedings of 21st IEEE/ACM International Conference on Mining Software Repositories (MSR), Lisbon, Portugal (2024)
Stocker, M., Zimmermann, O.: API refactoring to patterns: catalog, template and tools for remote interface evolution. In: Proceedings of 28th European Conference on Pattern Languages of Programs (EuroPLoP). ACM (2023)
Zhang, L., et al.: Has my release disobeyed semantic versioning? Static detection based on semantic differencing. In: Proceedings of the 37th IEEE/ACM International Conference on Automated Software Engineering, pp. 1–12 (2022)
Zimmermann, O., Stocker, M., Lubke, D., Zdun, U., Pautasso, C.: Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley, Boston (2022)
Author information
Authors and Affiliations
Corresponding author
Editor information
Editors and Affiliations
Rights and permissions
Copyright information
© 2024 The Author(s), under exclusive license to Springer Nature Switzerland AG
About this paper
Cite this paper
Serbout, S., Pautasso, C. (2024). How Many Web APIs Evolve Following Semantic Versioning?. In: Stefanidis, K., Systä, K., Matera, M., Heil, S., Kondylakis, H., Quintarelli, E. (eds) Web Engineering. ICWE 2024. Lecture Notes in Computer Science, vol 14629. Springer, Cham. https://doi.org/10.1007/978-3-031-62362-2_25
Download citation
DOI: https://doi.org/10.1007/978-3-031-62362-2_25
Published:
Publisher Name: Springer, Cham
Print ISBN: 978-3-031-62361-5
Online ISBN: 978-3-031-62362-2
eBook Packages: Computer ScienceComputer Science (R0)