Eng Cn Translate this page:
Please select your language to translate the article


You can just close the window to don't translate
Library
Your profile

Back to contents

Software systems and computational methods
Reference:

A Single Specification Format as a Microservice API Artifact when Using API-First

Volushkova Vera L'vovna

PhD in Technical Science

Associate Professor, Department of Computer Science, Tver State University

170004, Russia, Tverskaya oblast', g. Tver', pr-d 2-Oi stakhanovskii, 47

w2lvera@gmail.com
Other publications by this author
 

 
Volushkova Aleksandra Yurievna

Java Backend Developer, Axenix LLC

115054, Russia, Moscow region, Moscow, Paveletskaya str., 2,p.2

sobakasasha114@gmail.com

DOI:

10.7256/2454-0714.2022.4.39235

EDN:

MFEXNN

Received:

23-11-2022


Published:

30-12-2022


Abstract: The object of research is the interaction protocols (API - Application Programming Interface) of microservices. The microservices API is an important development object because each microservice can be a client for any other microservice and be created by a separate team. To build a unified system of interaction between microservices, the API-First methodology for synchronizing communication protocols for server applications was used. The aim of the work is to create a way to develop API microservices of server java applications using spring-boot, spring-web, openapi-generator, springdoc libraries. The method is based on the fact that the API is the most important part of the product and therefore is created at the initial design stage. An approach based on a single microservices API and TDD testing technique is proposed, which increases the efficiency of managing the development of server-side java applications. The microservices API is built using the specification as the API artifact. The developed technique allows: use the created API by another team, regardless of the development language; increase the productivity of development teams; to carry out a qualitative description of methods and models; reduce the amount of routine code by generating code from the specification; identify API design errors earlier than with the standard development approach (API after implementation) by applying TDD and working with the API before it is implemented.


Keywords:

API, API-First, code-frist, testing, TDD technique, microservices, Application server, development cycle, Rest client, spring

This article is automatically translated. You can find original text of the article here.

API-First is a way of creating enterprise applications, in which the API has the highest priority and is created at the initial design stage [1][2]. Microservices play an important role in corporate applications. When using API-First, the creation of the service should start with the API. This is a rather rare approach to creating microservices.

The average IT manager considers creating an API before creating a microservice to be an inefficient, outdated, classic way of working on a project. API-First is actually the implementation of the traditional stages of development: analysis, design, development. It is believed that Agile is not an outdated approach to design[3].

The proposed approach to API design can also be used in the Agile methodology. In Agile, it is possible to create documentation before the task itself is completed. The use of Agile methodology can lead to different protocols of interaction between microservices due to multiple changes and the implementation of different versions. The methodology proposed in the paper for creating server applications allows you to maintain a single format of interaction protocols in the form of an API artifact.

The microservice API has its own creation sequence in which an API artifact is created. The service being designed has a dependency on the API artifact. This ensures the significance of the specification in the artifact. Thus, the order of development of the microservice API implies the initial creation of the API, and then its implementation in the world service. The above procedure for creating services is the main one when using the API-First paradigm, but does not define it. From the definition of First, it follows that the creation of an API interface is the first stage in application development. The dependence of microservices on the API is shown in Figure 1.

Figure 1. Microservices API

Creating a single API within API-First allows you to:

develop simultaneously: API-using application, tests, API implementation;

develop an application using the API in any language;

have a mandatory design stage API development;

always have an up-to-date API specification;

reduce the possibility of design errors;

reduce labor costs for design.

Creating a single API can change the classic code-frist development cycle [4], which consists in the fact that the API is created after the services are created. Let's say a new microservice is being implemented or the API of an existing service is being changed. At the same time, it is necessary that the API specification meets the business requirements. In the classic development cycle, it is allowed to check API compliance with business requirements only after API implementation. If an error is found in the specification, there will be changes in both the specification and the implementation of the API, as shown in [5]. Testing teams and teams creating an application using the API must wait for the API implementation to be completed. This process is shown in Fig. 2

Figure 2. The development process in the Code first design architecture

The API-First architecture makes it possible to avoid a long wait for design teams. The developed API must be implemented both in the application using the API and in the service implementing the API. To successfully promote the API, it is proposed to apply the TDD (test-driven development) design method[6][7]. At the stage of creating tests, it is allowed to check the API specification.

We can say that from the moment the tests are developed, the stage of creating a new version of the API begins. At the same time, the team creating the client develops tests in which the API call affects the operation of the client application. In the tests of this stage, the result of the API call is reproduced using Mock. This is how the use of the service API in further developments is simulated. With the help of these tests, you can additionally control the API specification, namely:

does the API meet the conditions;

is it possible to optimize the number of service calls;

whether the transmitted information meets the requirements.

Such testing will not change the effectiveness of the team. Performance may even improve if a bug is found.

Tests can be created both in an application using the API and in a service implementing the API. Tests in the service determine whether it is possible to implement the requirements specified in the API specification, namely, whether the available and provided data is sufficient. Thanks to testing, API design errors will be detected even before it is created. This makes it possible to correct the design flaws of the API when designing it. The API before implementation is much easier to change than the service itself. The development process in the API-First architecture using the TDD technique is shown in Figure 3.

Figure 3. The development process in the API-First architecture using the TDD technique

If the API implementing application is a client application, the simultaneous operation scenario is also observed. The frontend team starts working immediately after the release of the final version of the API. The test bench is deployed following the implementation of the API. Installing the service on the stand allows the testing team to get started.

The above design architecture allows all API implementing teams to work in parallel. At the same time, API specification errors are detected earlier than in the Code first design architecture.

The process of creating software in the API-First architecture when using the TDD technique gives the following advantages:

simultaneous work of different development teams;

the correctness of the API documentation, which will not differ from the API implementation documentation because there is a special API product that implements the service and the client of this service;

detection of errors in the microservices API before their development, because the design highlights the stage of API creation according to the specification.

Let's consider how to practically create a single specification format as an API artifact of a microservice. We will accept the following provisions.

An API application consists of two projects API creation and API implementation.

The API specification is a SNAPSHOT API, which is a separate artifact. API changes first mean changing the API specification on which the service implementing the API and consumer applications depend. The teams creating client applications take the modified API artifact. Then they check whether the created API is suitable for the team. In parallel, based on the API specification, the team creating the services has the ability to generate tests for the API.

Interface development is a complete project. Therefore, the team creating the application using the API and the team implementing the interface service have the opportunity to check the correctness of the specification and create a release API artifact.

The http API is described using the OPENAPI 3 specification[8].

Let's look at how this protocol is used in an application created in springboot. The project is built using the following steps:

API artifact development;

formation of models on the server, creation of interfaces;

creating client code.

The artifact API assembly consists of: checking the specification, creating an artifact, publishing an artifact.

To create an API project, you need to complete seven steps, which are described in detail in [9].

API artifacts appear in the repository after building projects for the formation of interfaces. API artifacts are presented as a zip archive. The archive has one file. API artifacts will be included as dependencies in our projects.

For example, if we consider two ApiFirstMockClient projects, ApiFirstMock and the nexus repository, then the inclusion of dependencies is shown in Figure 5.

https://habrastorage.org/r/w1560/getpro/habr/upload_files/379/b21/684/379b216849d6240f697b3ed4e628b005.png

Figure 4. API artifacts as dependencies

Let's show you how to form an application on the server, while using the API in another service. Building a server application project includes: extracting an API artifact from the repository, unpacking this artifact, generating code according to the specification and including it in the project source directory.

How this sequence is performed is shown in [9].

As a result of these four stages, the openApiGenerate stage will be added to the project. The models on the server are created automatically based on the specification. Interfaces will also be generated. The generated interfaces can be accessed when creating controllers.

Consider creating client code. In this example, the client is represented by an application on the server. How the server application is generated is described above.

The assembly of the application project consists of four steps: extracting the client interface and the server interface from the repository, unpacking artifacts, generating code according to the relevant specifications and connecting to the project source directory.

For more information about creating a server and client, see [9].

Generating a Feign client [10], which simplifies writing web service clients, is also described in detail in [9].

The article discusses the creation of microservices using the specification as an API artifact. The development process using the API-First design architecture and TDD techniques is proposed. This way of designing microservices allows:

Use the API developed by another team, regardless of the project language.

Perform simultaneous creation of different parts of the project. Testers, the API client creation team, and the service development team implementing the interface can work simultaneously using a ready-made API. This reduces the development time.

Qualitatively document methods and models, due to the mandatory preliminary description of the interface.

Reduce the amount of manual program writing, because the code is generated automatically from the specification. The interface documentation has a convenient visual representation (swagger-ui [11]). The documentation and the code will be coordinated due to the fact that it is based on the documentation that the service program is created. Therefore, the specification will always be represented by the current version.

Identify API design errors earlier than in the code-frist design architecture by using parallel testing and working with the interface before its implementation. This minimizes the costs caused by errors in the documentation.

References
1. Medjaoui M., Amundsen M., Mitra R., Wilde E. (2021). Continuous API Management. SPB: Piter.
2. Janet Wagner. (2020). Understanding the API-First Approach to Building Products. Retrieved from https://swagger.io/resources/articles/adopting-an-api-first-approach.
3. The Agile Software Development Manifesto. Retrieved from http://agilemanifesto.org/iso/ru/manifesto.html.
4. Polyanin M. (2020). What is Design first and Code first in Code (Yandex Practicum magazine). Retrieved from https://thecode.media/design-first/
5. V.L.Volushkova Integraciya raznorodnyh dannyh v korporativnyh informacionnyh sistemah // Programmnye sistemy i vychislitel'nye metody. 2019. 1. . 81-90. DOI: 10.7256/2454-0714.2019.1.28768 URL: https://nbpublish.com/library_read_article.php?id=28768
6. Beck K. (2003). Test-Driven Development by Example. Addison Wesley.
7. Eric Elliott. (2019). TDD Changed My Life. Retrieved from https://medium.com/javascript-scene/tdd-changed-my-life-5af0ce099f80.
8. OpenAPI Specification. Retrieved from https://swagger.io/specification.
9. Volushkova A. (2022). API-First i mikroservisy URL: https://habr.com/ru/company/axenix/blog/694340.
10. Spring Cloud OpenFeign. Retrieved from https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html.
11. Swagger UI. Retrieved from https://swagger.io/tools/swagger-ui/.

Peer Review

Peer reviewers' evaluations remain confidential and are not disclosed to the public. Only external reviews, authorized for publication by the article's author(s), are made public. Typically, these final reviews are conducted after the manuscript's revision. Adhering to our double-blind review policy, the reviewer's identity is kept confidential.
The list of publisher reviewers can be found here.

The subject of research is the way to create enterprise applications, in which the API has the highest priority and is created at the initial design stage. The article describes in detail the algorithm for creating and testing microservices using the specification as an API artifact. The principle of practical creation of a single specification format as an API artifact of a microservice under certain assumptions is considered. Namely: a) the API application consists of two projects API creation and API implementation; b) the API specification is a SNAPSHOT API, which is a separate artifact. API changes first mean changing the API specification on which the service implementing the API and consumer applications depend. The teams creating the client applications take the modified API artifact. Then they check whether the created API is suitable for the team. In parallel, based on the API specification, the team creating the services has the ability to generate tests for the API. Interface development is a complete project. Therefore, the team creating the application using the API and the team implementing the interface service have the opportunity to verify the correctness of the specification and create a release API artifact. The development process using the API-First design architecture and TDD techniques is proposed. This method of design, according to the authors of the development, allows you to achieve the following advantages. first of all, it becomes possible to use the API developed by another team, regardless of the project language used. This will cause a significant reduction in labor costs and the duration of the project. In addition, the proposed approach allows you to simultaneously create different parts of the project. Testers, the API client creation team and the service development team implementing the interface can work simultaneously using a ready-made API, which reduces the overall development time. The authors also assume that their creation algorithm will allow not only to document methods and models qualitatively, due to the mandatory preliminary description of the interface, but also to reduce the amount of manual writing of programs, since the code is generated automatically from the specification. Since the interface documentation has a convenient visual representation (swagger-ui), the actual documentation and code being developed will be coordinated due to the fact that the service program is created based on the documentation. Therefore, the specification will always be represented by the current version. The undoubted advantage of the proposed algorithm is the ability to identify API design errors earlier than in the code-frist design architecture by using parallel testing and working with the interface before its implementation. This minimizes the costs caused by errors in the documentation. There is no scientific novelty in the work, since it is aimed at solving a specific applied problem and does not establish new patterns and facts previously unknown to the scientific community. At the same time, the work is relevant and may be of interest to specialists involved in creating microservices using the specification as an API artifact. The style, structure and method of presentation of the material is debatable and needs logical adjustment. However, this reviewer's opinion is private and does not reduce the practical value of the semantic content of the article, which can be published in the author's editorial office.