Abstract
IDE’s (Integrated Development Environments) are powerful tools to support the development process and help to write better and cleaner code. However, most IDEs aim with their support on the development of monolithic software. For the development of distributed systems like a microservices-based system, there is a lack of IDE support for e.g. inter-service communication via REST. This means through the string-based communication used during REST, the IDE is not able to support with autocompletion, syntax highlighting or type checking. To solve this issue, we introduce an IDE plugin called SIARest (Software Interface Analyser), based on the LSP (Language Server Protocol), which gives additional support during the development of distributed microservice-based systems, in a monorepo environment.
You have full access to this open access chapter, Download conference paper PDF
Similar content being viewed by others
Keywords
1 Introduction
In this paper, we will introduce a new IDE plugin hereinafter referred to as SIARest, which enables commonly used IDE features, like type checking, syntax highlighting and autocompletion, to the microservice cosmos. Currently, these features are limited to monolithic applications. In this chapter we will describe our motivation and highlight the goals of this paper through research questions, also we will give a short overview of the related work. In the second chapter, we will introduce some basic knowledge. Afterwards, in the third chapter, SIARest will be presented. The fourth chapter will summarize the presented knowledge and answers the research questions of this paper. The final chapter will give a short outlook to the upcoming work.
1.1 Motivation
Writing code documentation is often seen as chores. But, without a proper documentation, the usage of a REST API is nearly impossible. The problem that comes with tools like Swagger (see Sect. 1.3) is that the generated documentation needs to be synchronized with the written code manually. Even if Swagger is able to generate an API service from an OpenAPI description, this code needs to be adjusted manually. This in turn brings deviation between code and documentation. From the idea to automatically check the API documentation against the written code, the way was short to come up with an IDE integration through a plugin which can check an implemented API service against an API specification.
In Sect. 1.2, we discuss other solutions and contrast them with our own. The Sect. 2 will introduce basic knowledge for the further descriptions. After this, in Sect. 3, we briefly introduce the actual implemented plugin. The conclusion and the future work are presented in Sect. 4 and 5.
1.2 Related Work
The most tooling for development of REST services are interactive testing tools like PostmanFootnote 1 or CurlFootnote 2. They are used after a REST API is implemented to check the correctness of the API through predefined testing scenarios. In comparison to our plugin, these tools are not directly integrated into the development cycle, because they are not directly integrated into the IDE to give direct feedback about the implementation. However, Visual Studio Code offers a pluginFootnote 3 for API testing from the IDE. But, the problem of the lack of integration into the development cycle is still present.
Another tool which is often used for REST endpoints is SwaggerFootnote 4. With Swagger, it is possible to describe a REST API with the OpenAPIFootnote 5 specification. From this specification, Swagger can generate an online documentation for a REST API. Even more, it is possible to try the API in a generated web page, which could be served through any web server. Swagger can be integrated into the development cycle through annotations. This is available for most backend libraries in various languages like Spring Boot (Java) [13] or NestJS (TypeScript) [9]. Through this, it is possible to generate the Swagger documentation and web page directly from the code. However, this process has no IDE support. The IDE will not highlight deviated descriptions from an annotation with the actual implemented code. SIARest is able to highlight wrongly implemented endpoints.
In “SafeRESTScript: Statically Checking REST API Consumers”, Nuno Burnay et al. presents a new language which should allow static validation of REST endpoints [3]. The language is called SafeRESTScript and leans syntactically on JavaScript. The specification for validation is written in HeadREST [14], which can be compared to the OpenAPI specification used by Swagger. The approach of Nuno Burnay et al. relies on model checking methods. They created a new language to write REST endpoints. For their ecosystem, this may be a good strategy to ensure correctness of REST API. However, this also means that developers needs to reimplement their services with SafeRESTScript and also need to specify their services with HeadREST. This is a very hard change of the development circle. SIARest can be used after the implementation to check for correctness, a reimplementation is not needed.
Another formal approach is presented in Formal Verification of Stateful Services with REST APIs Using Event-B by Irum Rauf et al. [11]. The authors use the Event-B [1] modeling tool to address inconsistency design issues, model checking of service specifications and the state-explosion problem [11]. Their solution could be integrated into a continuous integration pipeline. In contrast to our plugin, the pipeline do not provide feedback instantaneous to the developer.
Beside the formal approaches, there are more practicable tools which provides a similar set of features than our plugin. In the paper Statically Checking Web API Requests in JavaScript, the authors also created a tool which is able to check an API specification against an implementation with JavaScript, JQueryFootnote 6 and AjaxFootnote 7 [15]. The same authors have integrated this tool into the IDE Atom [16]. Regardless, this integration is a popup which shows current problems with the actual API implementation. The plugin does not provide directly interaction with the developer through well known IDE features like syntax highlighting.
2 Basics
This chapter will give a brief introduction to the Monorepo pattern and the Language Server Protocol. We will describe shortly the technologies and the usage in the context of SIARest.
2.1 Monorepo
The Monorepo is a pattern for project organization. Rather than managing every project in its own Git repository, a Monorepo controls all projects in a single Git repository at once [4]. Although, the code is managed by one repository, each service still can be developed and deployed independently [6].
Beside the technical advantages of Monorepos like one source of truth, code reuse, atomic changes [7], there are social benefits. The developers work together on a single product in a single repository without any restriction of visibility or access control. This can improve the cohesion of a team [2]. However, the downsides of Monorepos are lack of access control, long build times and the bad performance of git on huge repositories [7]. The fact that big companies like Google [10], Facebook [8] and Microsoft [5] also use Monorepos shows that this pattern is production ready.
To use the full feature set of SIARest, we currently recommend organizing the code of multiple services in a Monorepo. This regards to the feature of showing of and jumping to REST API methods.
2.2 Language Server Protocol
The Language Server ProtocolFootnote 8 defines the communication between an editor or IDE and a Language Server. It was created and maintained by Microsoft. The source code is available on GitHub in the Microsoft organizationFootnote 9.
The Language Server runs as a separate child process of an editor or IDE. The communication between parent and child process takes place using the JSON-RPC protocol and works similar to REST APIs [12]. Therefore, it standardizes what is received by the Language Server and what is sent back to the editor or IDE.
Many coding features like autocompletion, GoTo definition, or documentation on hover for a programming language are supported by the protocol. It is used by multiple different Language Servers like the CSS Language ServerFootnote 10 or the TypeScript Language ServerFootnote 11 which are included in Visual Studio Code.
3 SIARest
Currently, SIARest is only working for Express backends and Angular frontends written in TypeScript.
SIARest is an extension for Visual Studio CodeFootnote 12. It implements the Language Server Protocol to provide coding features for the development of web applications based on TypeScript and ExpressFootnote 13. These features includes syntax highlighting, autocompletion, GoTo definitions, and hover infos.
SIARest consist of three parts. The extension, which is necessary to communicate with Visual Studio Code and the Language Server. The Language Server, resolves the request redirected from Visual Studio Code by the extension. A configuration file, which contains definitions of endpoints for the corresponding web application.
For simplicity, we refer Visual Studio Code and the extension as the client and the Language Server as the server.
The client and the server use the Language Server Protocol to exchange requests and responses. Requests like opening, editing or saving a file trigger the analysis process for TypeScript files. Afterwards, the server transforms the associated file to an abstract syntax tree. For this transformation, we use the TypeScript Compiler APIFootnote 14.
Next, we parse the abstract syntax tree and search for typical phrases of the Express framework. These phrases could be expressions like app = express();Footnote 15 or router = Router();Footnote 16.
If such phrases are found, we can expect that this file uses the web framework and we start with a deep structural analysis. During the deep analysis, we are looking for expressions that define API endpoints. To be precise, we are looking at HTTP methods, like GET, POST or DELETE.
If there are endpoints present, we cache the results to be able to analyze them in more detail. Since SIARest provides support for syntax highlighting, we want to show errors or warnings directly after the user is editing a file. Because of this, we start to check the cached results for errors or warnings with the help of our configuration file directly after traversing the abstract syntax tree.
The following Fig. 1 shows an example for the syntax highlight which is provided by SIARest.
To know which values are wrong, our configuration file is used. This file is a JSON file and holds information about the API and its endpoints. In a nutshell, the configuration consists of multiple service description which consist of multiple endpoint definitions. The syntax is inspired by the OpenAPI specification, but is simplified and minimized. Currently, this configuration file needs to be written by hand. In Chap. 5 we discuss a possible solution for this issue.
Further features like GoTo definitions or reference search for API URLs are also supported. At the moment, these features are only available for monorepos. In both features, SIARest searches for the usages of API URLs from an express project in Angular frontends and vice versa. Through this, it is possible to “jump” between the definition and the reference of API endpoints. To find these references and definitions the cached results of the analysis process are used.
The Hover feature shows specific information about endpoints inside the editor. It uses the information from the configuration file and creates a readable string that shows information when hovering over an API address. The information contains the URL Address, type of the endpoint, and both types of the request and/or result objectFootnote 17.
The last feature is the autocompletion. It takes the information from each entry of the configuration file and takes the address to suggest it for autocompletion. This is shown in Fig. 2.
For the sake of replication, you can find SIARestFootnote 18 and a simple example projectFootnote 19 with a running configuration on GitHub.
4 Conclusion
In this paper, we introduced the Visual Studio Code plugin SIARest, which brings common coding support to the microservice-based development of web applications. Unfortunately, we have not tested the plugin in a bigger manner with more than several test users. Hence, we want to bring a first version of the plugin into the Visual Studio Code Marketplace to reach a bigger user base and to collect feedback for further improvements.
5 Future Work
For our next steps, we want to remove the necessity of a configuration file. This could be achieved through the integration of an already existing specification like OpenAPI. This also ensures that the API documentation never deviate from the actual implementation, because of the type checking during development time. Furthermore, we want to erase the requirement of the monorepo to use all features of SIARest. SIARest should be easy as possible, so the integration barrier is as low as possible for developers. Finally, SIAREST needs to integrate more libraries and technologies like SpringBoot(Java) or NestJS (TypeScript) and also should support more IDEs then Visual Studio Code. Because of the usage of the Language Server Protocol, the integration of SIARest into other IDEs should be easy.
Notes
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
- 16.
- 17.
- 18.
- 19.
References
Abrial, J.-R.: Modeling in Event-B: System and Software Engineering. Cambridge University Press (2010). https://doi.org/10.1017/CBO9781139195881
Brousse, N.: The issue of Monorepo and Polyrepo in large enterprises. In: Proceedings of the Conference Companion of the 3rd International Conference on Art, Science, and Engineering of Programming, Programming 2019, New York, NY, USA, 2019. Association for Computing Machinery. https://doi.org/10.1145/3328433.3328435
Burnay, N., Lopes, A., Vasconcelos, V.T.: Statically checking REST API consumers. In: de Boer, F., Cerone, A. (eds.) SEFM 2020. LNCS, vol. 12310, pp. 265–283. Springer, Cham (2020). https://doi.org/10.1007/978-3-030-58768-0_15
From monolith to monorepo. https://medium.com/@brockreece/from-monolith-to-monorepo-19d78ffe9175. Accessed 22 Mar 2022
Microsoft now uses git and GVFS to develop windows. https://techcrunch.com/2017/05/24/microsoft-now-uses-git-and-gvfs-to-develop-windows/. Accessed 22 Mar 2022
Misconceptions about monorepos: Monorepo != monolith. https://blog.nrwl.io/misconceptions-about-monorepos-monorepo-monolith-df1250d4b03c. Accessed 22 Mar 2022
The pros and cons of monorepos, explained. https://betterprogramming.pub/the-pros-and-cons-monorepos-explained-f86c998392e1. Accessed 12 Jul 2022
Scaling mercurial at facebook. https://engineering.fb.com/2014/01/07/core-data/scaling-mercurial-at-facebook/. Accessed 22 Mar 2022
OpenAPI integration in NestJS. https://docs.nestjs.com/openapi/introduction. Accessed 22 Mar 2022
Potvin, R., Levenberg, J.: Why google stores billions of lines of code in a single repository. Commun. ACM 59(7), 78–87 (2016). https://doi.org/10.1145/2854146
Rauf, I., Vistbakka, I., Troubitsyna, E.: Formal verification of Stateful services with rest APIs using event-B. In: 2018 IEEE International Conference on Web Services (ICWS), pp. 131–138 (2018). https://doi.org/10.1109/ICWS.2018.00024
Language server protocol overview. https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/. Accessed 26 Mar 2022
Setting up swagger 2 with a spring REST API. https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api. Accessed 22 Mar 2022
Vasconcelos, V.T., Martins, F., Lopes, A., Burnay, N.: HeadREST: a specification language for RESTful APIs. In: Boreale, M., Corradini, F., Loreti, M., Pugliese, R. (eds.) Models, Languages, and Tools for Concurrent and Distributed Programming. LNCS, vol. 11665, pp. 428–434. Springer, Cham (2019). https://doi.org/10.1007/978-3-030-21485-2_23
Wittern, E., Ying, A.T.T., Zheng, Y., Dolby, J., Laredo, J.A.: Statically checking web API requests in JavaScript. In: 2017 IEEE/ACM 39th International Conference on Software Engineering (ICSE), pp. 244–254 (2017). https://doi.org/10.1109/ICSE.2017.30
Wittern, E., et al.: Opportunities in software engineering research for web API consumption. In: 2017 IEEE/ACM 1st International Workshop on API Usage and Evolution (WAPI), pp. 7–10 (2017). https://doi.org/10.1109/WAPI.2017.1
Author information
Authors and Affiliations
Corresponding author
Editor information
Editors and Affiliations
Rights and permissions
Open Access This chapter is licensed under the terms of the Creative Commons Attribution 4.0 International License (http://creativecommons.org/licenses/by/4.0/), which permits use, sharing, adaptation, distribution and reproduction in any medium or format, as long as you give appropriate credit to the original author(s) and the source, provide a link to the Creative Commons license and indicate if changes were made.
The images or other third party material in this chapter are included in the chapter's Creative Commons license, unless indicated otherwise in a credit line to the material. If material is not included in the chapter's Creative Commons license and your intended use is not permitted by statutory regulation or exceeds the permitted use, you will need to obtain permission directly from the copyright holder.
Copyright information
© 2024 The Author(s)
About this paper
Cite this paper
Copei, S., Schreiter, M., Zündorf, A. (2024). Improving the Implementation of Microservice-Based Systems with Static Code Analysis. In: Kruchten, P., Gregory, P. (eds) Agile Processes in Software Engineering and Extreme Programming – Workshops. XP XP 2022 2023. Lecture Notes in Business Information Processing, vol 489. Springer, Cham. https://doi.org/10.1007/978-3-031-48550-3_4
Download citation
DOI: https://doi.org/10.1007/978-3-031-48550-3_4
Published:
Publisher Name: Springer, Cham
Print ISBN: 978-3-031-48549-7
Online ISBN: 978-3-031-48550-3
eBook Packages: Computer ScienceComputer Science (R0)