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.

Fig. 1.
figure 1

Syntax Checking

Full size image

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.

Fig. 2.
figure 2

Autocompletion

Full size image

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.