How Are Web APIs Versioned in Practice? A Large-Scale Empirical Study
DOI:
https://doi.org/10.13052/jwe1540-9589.2341Keywords:
API, Web API, OpenAPI, empirical study, versioningAbstract
Web APIs form the cornerstone of modern software ecosystems, facilitating seamless data exchange and service integration. Ensuring the compatibility and longevity of these APIs is paramount. This study delves into the intricate realm of API versioning practices, a crucial mechanism for managing API evolution. Exploring an expanded and diverse dataset of 603 293 APIs specifications created during the 2015–2023 timeframe and gathered from four different sources, we examined the adoption of the following versioning practices: Metadata-based, URL-based, Header-based and Dynamic versioning, with one or more versions in production. API developers use more than 50 different version identifier formats to encode information about the changes introduced with respect to the previous version (i.e., semantic versioning), about when the version was released (i.e., age versioning) and about which phase of the API development lifecycle the version belongs (i.e., stable vs. preview releases).
Downloads
References
Semantic Versioning. https://semver.org/.
https://github.com/USI-INF-Software/API-Versioning-practices-detection.
Vercel API. https://vercel.com/docs/rest-api/endpoints.
OpenAPI Initiative. https://www.openapis.org/.
SwaggerHub API. https://app.swaggerhub.com/apis-docs/swagger-hub/registry-api/1.0.67.
https://docs.npmjs.com/about-semantic-versioning.
Release naming conventions. https://www.drupal.org/node/1015226.
https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/.
Google BigQuery. https://github.com/topics/bigquery.
Contextual Content Discovery: You’ve forgotten about the API endpoints. https://blog.assetnote.io/2021/04/05/contextual-content-discovery/.
Christopher Bogart, Christian Kästner, James Herbsleb, and Ferdian Thung. How to break an API: cost negotiation and community values in three software ecosystems. In Proc. 24th International Symposium on Foundations of Software Engineering, pages 109–120, 2016.
Alexandre Decan, Tom Mens, Pooya Rostami Mazrae, and Mehdi Golzadeh. On the use of github actions in software development repositories. In International Conference on Software Maintenance and Evolution (ICSME), pages 235–245, 2022.
Fabio Di Lauro, Souhaila Serbout, and Cesare Pautasso. A large-scale empirical assessment of web api size evolution. Journal of Web Engineering, 21(6):1937–1980, 2022.
Jens Dietrich, David Pearce, Jacob Stringer, Amjed Tahir, and Kelly Blincoe. Dependency versioning in the wild. In Proc. 16th International Conference on Mining Software Repositories (MSR), pages 349–359, 2019.
Tiago Espinha, Andy Zaidman, and Hans-Gerhard Gross. Web api growing pains: Loosely coupled yet strongly tied. Journal of Systems and Software, 100:27–43, 2015.
Anthony Giretti. API versioning. In Beginning gRPC with ASP.NET Core 6, pages 223–237, 2022.
Elias Grünewald, Paul Wille, Frank Pallas, Maria C Borges, and Max-R Ulbricht. Tira: an openapi extension and toolbox for gdpr transparency in restful architectures. In 2021 IEEE European Symposium on Security and Privacy Workshops (EuroS&PW), pages 312–319. IEEE, 2021.
Rediana Koçi, Xavier Franch, Petar Jovanovic, and Alberto Abelló. Web api evolution patterns: A usage-driven approach. Journal of Systems and Software, 198:111609, 2023.
Jun Li, Yingfei Xiong, Xuanzhe Liu, and Lu Zhang. How does web service api evolution affect clients? In 2013 IEEE 20th International Conference on Web Services, pages 300–307. IEEE, 2013.
Wenke Li, Feng Wu, Cai Fu, and Fan Zhou. A large-scale empirical study on semantic versioning in golang ecosystem. In 2023 38th IEEE/ACM International Conference on Automated Software Engineering (ASE), pages 1604–1614. IEEE, 2023.
Daniel Lübke, Olaf Zimmermann, Cesare Pautasso, Uwe Zdun, and Mirko Stocker. Interface evolution patterns: balancing compatibility and extensibility across service life cycles. In Proc. 24th EuroPLoP, 2019.
Klaus Marquardt. Patterns for software release versioning. In Proc. of the 15th European Conference on Pattern Languages of Programs (EuroPLoP), 2010.
Lina Ochoa, Thomas Degueule, Jean-Rémy Falleri, and Jurgen Vinju. Breaking bad? semantic versioning and impact of breaking changes in maven central. Empirical Software Engineering, 27(3):1–42, 2022.
Lianyong Qi, Houbing Song, Xuyun Zhang, Gautam Srivastava, Xiaolong Xu, and Shui Yu. Compatibility-aware web api recommendation for mashup creation via textual description mining. ACM Transactions on Multimidia Computing Communications and Applications, 17(1s):1–19, 2021.
Mikko Raatikainen, Elina Kettunen, Ari Salonen, Marko Komssi, Tommi Mikkonen, and Timo Lehtonen. State of the practice in application programming interfaces (APIs): A case study. In Proc. 15th European Conference on Software Architecture (ECSA), pages 191–206, 2021.
Steven Raemaekers, Arie van Deursen, and Joost Visser. Semantic versioning and impact of breaking changes in the maven repository. Journal of Systems and Software, 129:140–158, 2017.
Souhaila Serbout and Cesare Pautasso. An empirical study of web api versioning practices. In International Conference on Web Engineering, pages 303–318. Springer, 2023.
SM Sohan, Craig Anslow, and Frank Maurer. A case study of web api evolution. In 2015 IEEE World Congress on Services, pages 245–252. IEEE, 2015.
Aimilios Tzavaras, Nikolaos Mainas, Fotios Bouraimis, and Euripides GM Petrakis. Openapi thing descriptions for the web of things. In 2021 IEEE 33rd International Conference on Tools with Artificial Intelligence (ICTAI), pages 1384–1391. IEEE, 2021.
Aimilios Tzavaras, Nikolaos Mainas, and Euripides GM Petrakis. Openapi framework for the web of things. Internet of Things, 21:100675, 2023.
Jinqiu Yang, Erik Wittern, Annie TT Ying, Julian Dolby, and Lin Tan. Towards extracting web api specifications from documentation. In Proceedings of the 15th International Conference on Mining Software Repositories (MSR), pages 454–464, 2018.
Lyuye Zhang, Chengwei Liu, Zhengzi Xu, Sen Chen, Lingling Fan, Bihuan Chen, and Yang Liu. 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, pages 1–12, 2022.
Olaf Zimmermann, Mirko Stocker, Daniel Lübke, Uwe Zdun, and Cesare Pautasso. Patterns for API Design - Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley, 2022.
